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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@forloop-cc/forloop-opencode-plugin-planner",
-  "version": "2.2.23",
+  "version": "2.2.25",
   "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

@@ -144,6 +144,8 @@ export class ForLoopAPIClient {
       'organization:read',
       'organization:write',
       'organization:delete',
+      'a2a:read',
+      'a2a:write',
     ];
 
     const name = `lambda-planner-${Date.now()}`;
@@ -269,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',
@@ -369,6 +388,58 @@ export class ForLoopAPIClient {
     });
   }
 
+  async searchCoreServices(params: {
+    query?: string;
+    tool?: string;
+    directOnly?: boolean;
+    limit?: number;
+    offset?: number;
+    sprintId?: number;
+    subjectKey?: string;
+  } = {}): Promise<{ entries: any[]; total: number }> {
+    const search = new URLSearchParams();
+    if (params.query) search.set('q', params.query);
+    if (params.tool) search.set('tool', params.tool);
+    if (params.directOnly) search.set('direct', '1');
+    if (params.limit !== undefined) search.set('limit', String(params.limit));
+    if (params.offset !== undefined) search.set('offset', String(params.offset));
+    if (params.sprintId !== undefined) search.set('sprintId', String(params.sprintId));
+    if (params.subjectKey) search.set('subjectKey', params.subjectKey);
+    const query = search.toString();
+    return this.request(`/api/opencode/a2a/registry${query ? `?${query}` : ''}`);
+  }
+
+  async getCoreServiceContract(agentId: string, version: string): Promise<any> {
+    return this.request(
+      `/api/opencode/a2a/contracts/${encodeURIComponent(agentId)}/${encodeURIComponent(version)}`
+    );
+  }
+
+  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

@@ -68,6 +68,17 @@ import {
 } from './tools/agent-sprint-tools';
 import { createAITriggerTools } from './tools/ai-trigger-tools';
 import { createDeveloperStatusTool } from './tools/developer-status-tool';
+import {
+  createCoreServicesSearchTool,
+  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';
 
@@ -167,6 +178,19 @@ export default async (ctx: any) => {
       // AI Execution Tools
       ...aiTriggerTools,
       'forloopDeveloperStatus': createDeveloperStatusTool(client),
+
+      // Core-service discovery (read-only) + user-approval request
+      '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

@@ -0,0 +1,308 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId } from '../capabilities/context-resolver';
+import { getConfig } from '../capabilities/config';
+
+type RegistryEntry = {
+  agentId: string;
+  sprintId: number;
+  name: string;
+  kind?: 'system' | 'user';
+  description: string;
+  serviceCode?: string | null;
+  baseUrl?: string | null;
+  billingPrice?: number | null;
+  billingUnit?: string | null;
+  billingCurrency?: string | null;
+  version?: string | null;
+  versionStatus?: string | null;
+  sunsetAt?: string | null;
+  deprecatedAt?: string | null;
+  authMode?: 'none' | 'app' | 'user';
+  scopes?: { id: string; tier?: string; description?: string }[];
+  tools?: { id: string; name: string; description?: string; whenToUse?: string }[];
+  directIntegrable?: boolean;
+};
+
+const formatPrice = (entry: RegistryEntry): string => {
+  if (entry.billingPrice == null) return 'price TBD';
+  const currency = entry.billingCurrency || 'FLC';
+  const unit = entry.billingUnit ? ` per ${entry.billingUnit}` : ' per success';
+  return `${entry.billingPrice} ${currency}${unit}`;
+};
+
+const formatEntry = (entry: RegistryEntry, index: number): string => {
+  const lines = [
+    `${index + 1}. **${entry.name}** — ${entry.kind === 'system' ? 'ForLoop core service' : 'user app'}`,
+    `   - agentId: \`${entry.agentId}\``,
+    `   - kind: ${entry.kind ?? 'unknown'}`,
+    `   - serviceCode: ${entry.serviceCode ?? 'unknown'}`,
+    `   - baseUrl: ${entry.baseUrl ?? 'not published'}`,
+    `   - version: ${entry.version ?? 'unspecified'} (${entry.versionStatus ?? 'unknown'})${entry.sunsetAt ? `; sunset ${entry.sunsetAt}` : ''}`,
+    `   - price: ${formatPrice(entry)}`,
+    `   - auth: ${entry.authMode ?? 'none'}${entry.directIntegrable ? '; direct-integration enabled' : ''}`,
+    `   - scopes: ${(entry.scopes ?? []).map((scope) => scope.id).join(', ') || 'none declared'}`,
+    `   - description: ${entry.description || '(none)'}`,
+  ];
+  if (entry.tools?.length) {
+    lines.push('   - tools:');
+    for (const serviceTool of entry.tools) {
+      const guidance = serviceTool.whenToUse
+        ? ` — ${serviceTool.whenToUse}`
+        : serviceTool.description
+          ? ` — ${serviceTool.description}`
+          : '';
+      lines.push(`     - \`${serviceTool.id}\` (${serviceTool.name})${guidance}`);
+    }
+  }
+  return lines.join('\n');
+};
+
+const clientBaseUrl = (): string => {
+  const apiUrl = getConfig().apiUrl.replace(/\/+$/, '');
+  if (apiUrl.endsWith('api.dev.forloop.cc')) return 'https://dev.forloop.cc';
+  if (apiUrl.endsWith('api.forloop.cc')) return 'https://forloop.cc';
+  return apiUrl;
+};
+
+export function createCoreServicesSearchTool(client: ForLoopAPIClient) {
+  return tool({
+    description:
+      'Search ForLoop core services and directly-integrable peers by requirement. Use before designing a capability that may already exist (scheduling, notifications, payments). Results include kind, serviceCode, baseUrl, price, scopes, pinned version and tool guidance. Read-only.',
+    args: {
+      query: tool.schema
+        .string()
+        .optional()
+        .describe('Requirement sentence or keywords (tokenized; not a whole-phrase match)'),
+      tool: tool.schema.string().optional().describe('Tool id to match (e.g. create_schedule)'),
+      directOnly: tool.schema
+        .boolean()
+        .optional()
+        .describe('Only return peers that accept direct app integration'),
+      limit: tool.schema.number().optional().describe('Maximum results (default 10, max 100)'),
+    },
+    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);
+        const result = await client.searchCoreServices({
+          ...(args.query ? { query: args.query } : {}),
+          ...(args.tool ? { tool: args.tool } : {}),
+          ...(args.directOnly ? { directOnly: true } : {}),
+          limit: Math.min(Math.max(args.limit ?? 10, 1), 100),
+          ...(resolution.sprintId ? { sprintId: resolution.sprintId } : {}),
+        });
+
+        if (!result.entries?.length) {
+          return 'No matching core service was found. Say so plainly and plan to build the capability instead of inventing a service.';
+        }
+
+        return [
+          `Found ${result.entries.length} matching service${result.entries.length === 1 ? '' : 's'} (${result.total} total):`,
+          '',
+          ...result.entries.map((entry, index) => formatEntry(entry as RegistryEntry, index)),
+          '',
+          'Quote these fields when presenting the option; do not invent endpoints, scopes or versions.',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error searching core services: ${error.message}`;
+      }
+    },
+  });
+}
+
+export function createCoreServiceGetTool(client: ForLoopAPIClient) {
+  return tool({
+    description:
+      'Read a core service contract (OpenAPI + tool index) plus version status, deprecation and sunset. If version is omitted, the current registry version is resolved first. Read-only.',
+    args: {
+      agentId: tool.schema.string().describe('Service agentId (sprint public id)'),
+      version: tool.schema
+        .string()
+        .optional()
+        .describe('Pinned contract version; omit to use the current registry version'),
+    },
+    async execute(args) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) return tokenResult.error;
+      client.setToken?.(tokenResult.token);
+
+      try {
+        let version = args.version?.trim();
+        let entry: RegistryEntry | undefined;
+        if (!version) {
+          const found = await client.searchCoreServices({ query: args.agentId, limit: 50 });
+          entry = (found.entries ?? []).find(
+            (candidate: RegistryEntry) => candidate.agentId === args.agentId
+          ) as RegistryEntry | undefined;
+          if (!entry) {
+            return `❌ Core service \`${args.agentId}\` was not found in the registry.`;
+          }
+          if (!entry.version) {
+            return `❌ Core service \`${args.agentId}\` has no published contract version.`;
+          }
+          version = entry.version;
+        }
+
+        const contract = await client.getCoreServiceContract(args.agentId, version);
+        if (!entry && contract.sunsetAt === undefined) {
+          try {
+            const found = await client.searchCoreServices({ query: args.agentId, limit: 50 });
+            entry = (found.entries ?? []).find(
+              (candidate: RegistryEntry) => candidate.agentId === args.agentId
+            ) as RegistryEntry | undefined;
+          } catch {
+            entry = undefined;
+          }
+        }
+        const sunsetAt = contract.sunsetAt ?? entry?.sunsetAt ?? null;
+        const deprecatedAt = contract.deprecatedAt ?? entry?.deprecatedAt ?? null;
+        const status = contract.status ?? entry?.versionStatus ?? 'unknown';
+        const sunset = sunsetAt ? `\n- sunsetAt: ${sunsetAt}` : '\n- sunsetAt: none';
+        const deprecated = deprecatedAt ? `\n- deprecatedAt: ${deprecatedAt}` : '';
+        return [
+          `# ${args.agentId} — contract ${contract.version}`,
+          `- status: ${status}`,
+          `${sunset}${deprecated}`,
+          `- checksum: ${contract.checksum ?? 'unknown'}`,
+          '',
+          '## OpenAPI',
+          '```json',
+          JSON.stringify(contract.openapi, null, 2),
+          '```',
+          '',
+          '## Tool index',
+          '```json',
+          JSON.stringify(contract.index, null, 2),
+          '```',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error reading core service contract: ${error.message}`;
+      }
+    },
+  });
+}
+
+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.',
+    args: {
+      agentId: tool.schema.string().describe('Target core-service agentId'),
+      scopes: tool.schema
+        .array(tool.schema.string())
+        .describe('Exact scopes needed (must be declared by the service)'),
+      reason: tool.schema
+        .string()
+        .describe('Why the app needs this integration (shown to the user)'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) return tokenResult.error;
+      client.setToken?.(tokenResult.token);
+
+      try {
+        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) {
+          return `❌ Core service \`${args.agentId}\` was not found in the registry. Do not invent a connection request.`;
+        }
+
+        const declared = (target.scopes ?? []).map((scope) => scope.id);
+        const requested = Array.from(
+          new Set((args.scopes ?? []).filter((scope) => typeof scope === 'string' && scope.trim()))
+        );
+        if (!requested.length) {
+          return [
+            `❌ No scopes requested for \`${args.agentId}\`.`,
+            `Declared scopes: ${declared.join(', ') || 'none'}.`,
+          ].join('\n');
+        }
+        const undeclared = requested.filter((scope) => !declared.includes(scope));
+        if (undeclared.length) {
+          return [
+            `❌ These scopes are not declared by \`${args.agentId}\`: ${undeclared.join(', ')}`,
+            `Declared scopes: ${declared.join(', ') || 'none'}.`,
+          ].join('\n');
+        }
+
+        const resolution = await resolveSprintId(undefined, context?.directory);
+        const callerSprintId = resolution.sprintId ?? null;
+        const connectionPayload = {
+          callerSprintId,
+          targetAgentId: args.agentId,
+          subjectType: 'app' as const,
+          scopes: requested,
+        };
+
+        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 connectUrl = spaceUrl ? `${spaceUrl}?${linkParams.toString()}` : null;
+
+        const approvalSteps = 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 **Connect**.',
+              '4. Copy the **Connection ID** shown under the new connected app into the integration brief.',
+            ]
+          : [
+              `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.',
+            ];
+
+        return [
+          `## Integration approval required — nothing is created yet`,
+          `- Service: **${target.name}** (\`${target.agentId}\`)`,
+          `- serviceCode: ${target.serviceCode ?? 'unknown'}`,
+          `- reason: ${args.reason}`,
+          `- scopes: ${requested.join(', ')}`,
+          `- cost: ${formatPrice(target)}`,
+          '',
+          '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.',
+          '',
+          '### Approve now (creates the app-subject grant)',
+          ...approvalSteps,
+          '',
+          '### Connection payload (owner 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.',
+        ].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}`;
+      }
+    },
+  });
+}