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

package/package.json

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

package/plugins/capabilities/api-client.ts

@@ -144,6 +144,7 @@ export class ForLoopAPIClient {
       'organization:read',
       'organization:write',
       'organization:delete',
+      'a2a:read',
     ];
 
     const name = `lambda-planner-${Date.now()}`;
@@ -369,6 +370,33 @@ 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 summarizeConversation(sprintId: number): Promise<any> {
     return this.request(`/api/opencode/sprints/${sprintId}/summarize`, {
       method: 'POST',

package/plugins/capabilities/mime-types.ts

@@ -17,7 +17,10 @@ const MIME_TYPES: Record<string, string> = {
 };
 
 export function contentTypeFromExtension(ext: string): string {
-  return MIME_TYPES[String(ext || '').toLowerCase()] || 'application/octet-stream';
+  const base = MIME_TYPES[String(ext || '').toLowerCase()] || 'application/octet-stream';
+  // Text payloads are always UTF-8; without an explicit charset browsers fall
+  // back to Latin-1 and render multi-byte characters as mojibake.
+  return base.startsWith('text/') && !/charset/i.test(base) ? `${base}; charset=utf-8` : base;
 }
 
 export function formatFileSize(bytes: number): string {

package/plugins/forloop-plugin.ts

@@ -68,6 +68,11 @@ 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 { injectEnvironment } from './hooks/shell-env';
 import { createChatMessageHook, createEventHook } from './hooks/message-recorder';
 
@@ -167,6 +172,11 @@ 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),
     },
     event: createEventHook(client),
     'chat.message': createChatMessageHook(client),

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

@@ -0,0 +1,274 @@
+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:
+      '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.',
+    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,
+        };
+        const connectUrl = `${clientBaseUrl()}/myspace?connect=${encodeURIComponent(args.agentId)}`;
+
+        return [
+          `## Integration request — pending user approval`,
+          `- Service: **${target.name}** (\`${target.agentId}\`)`,
+          `- serviceCode: ${target.serviceCode ?? 'unknown'}`,
+          `- reason: ${args.reason}`,
+          `- scopes: ${requested.join(', ')}`,
+          `- cost: ${formatPrice(target)}`,
+          '',
+          'The planner does not create connections or handle credentials. Ask the user to approve this request in the UI.',
+          '',
+          '### 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.',
+          '',
+          '### Connection payload (owner/developer 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.',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error creating integration request: ${error.message}`;
+      }
+    },
+  });
+}