postfast-mcp 0.8.2 → 0.9.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "postfast",
       "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile.",
-      "version": "0.8.2",
+      "version": "0.9.0",
       "author": {
         "name": "PostFast",
         "email": "me@peturgeorgievv.com"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "postfast",
   "description": "Schedule, manage, and analyze social media posts via PostFast. Supports Facebook, Instagram, X, TikTok, LinkedIn, YouTube, BlueSky, Threads, Pinterest, Telegram, and Google Business Profile. Needs POSTFAST_API_KEY set before Claude Code starts; in PostFast, open API in the sidebar and click Generate API Key.",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "author": {
     "name": "PostFast",
     "email": "me@peturgeorgievv.com"
@@ -13,7 +13,7 @@
   "mcpServers": {
     "postfast": {
       "command": "npx",
-      "args": ["-y", "postfast-mcp@0.8.2"],
+      "args": ["-y", "postfast-mcp@0.9.0"],
       "env": {
         "POSTFAST_API_KEY": "${POSTFAST_API_KEY}"
       }

package/dist/core/app.d.ts

@@ -0,0 +1,42 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolIcon } from './tool-def.js';
+import type { AppEntrypoint } from './types.js';
+/**
+ * What a host passes to turn the calendar app on (BuildToolsOptions.app).
+ * Each value is an origin (scheme and host, no path) that differs per
+ * deployment.
+ */
+export interface AppOptions {
+    /** Serves the signed media URLs: the only origin the view loads images and video from. */
+    mediaOrigin: string;
+    /** The view's dedicated origin (`_meta.ui.domain`). */
+    domain: string;
+    /** The PostFast web app, target of the "Open in PostFast" links. */
+    webAppUrl: string;
+}
+/** Versioned: a change an open view can't handle ships under a new URI. */
+export declare const APP_RESOURCE_URI = "ui://postfast/app-v1";
+export declare const APP_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/** Throws unless every option is a bare origin: https, or http on a loopback host. */
+export declare function assertAppOptions(app: AppOptions): void;
+/**
+ * Tool `_meta` for the app. With an entrypoint, the tool opens the view and is
+ * listed in the host's sidebar (global) or as a conversation tab (thread);
+ * without one, only the view can call it. Every app tool is hidden from the
+ * model.
+ */
+export declare function appToolMeta(entrypoint?: AppEntrypoint): Record<string, unknown>;
+/** The entrypoint icon in tools/list. */
+export declare const APP_ICON: ToolIcon;
+/** The built view, one self-contained HTML file (dist/view/index.html), read once. */
+export declare function appViewHtml(): string;
+/** Registers the view as the app's UI resource. */
+export declare function registerAppResource(server: McpServer, app: AppOptions): void;
+/**
+ * Lists icons on the named tools in tools/list. McpServer has no field for
+ * tool icons, so this wraps its tools/list handler and adds `icons` to those
+ * tools only; every other field stays the SDK's own output. If the SDK keeps
+ * its handlers elsewhere, the icons are skipped with a log and the host falls
+ * back to the app's own logo.
+ */
+export declare function listToolIcons(server: McpServer, icons: Map<string, ToolIcon[]>): void;

package/dist/core/app.js

@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+/** Versioned: a change an open view can't handle ships under a new URI. */
+export const APP_RESOURCE_URI = 'ui://postfast/app-v1';
+export const APP_RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app';
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** Throws unless every option is a bare origin: https, or http on a loopback host. */
+export function assertAppOptions(app) {
+    for (const key of ['mediaOrigin', 'domain', 'webAppUrl']) {
+        const value = app?.[key];
+        let url;
+        try {
+            url = new URL(value);
+        }
+        catch {
+            url = undefined;
+        }
+        const secure = url?.protocol === 'https:' ||
+            (url?.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname));
+        if (!url || !secure || url.origin !== value) {
+            throw new Error(`app.${key} must be an https origin with no path, such as https://example.com; got ${JSON.stringify(value)}.`);
+        }
+    }
+}
+/**
+ * Tool `_meta` for the app. With an entrypoint, the tool opens the view and is
+ * listed in the host's sidebar (global) or as a conversation tab (thread);
+ * without one, only the view can call it. Every app tool is hidden from the
+ * model.
+ */
+export function appToolMeta(entrypoint) {
+    if (!entrypoint) {
+        return { ui: { visibility: ['app'] } };
+    }
+    return {
+        ui: { resourceUri: APP_RESOURCE_URI, visibility: ['app'] },
+        // The flat key older hosts read; ext-apps' registerAppTool writes both.
+        'ui/resourceUri': APP_RESOURCE_URI,
+        'openai/ui': { entrypoints: [{ type: entrypoint }] },
+        'openai/iconStyle': 'monochrome',
+    };
+}
+/** Resource `_meta`: images and video only from the media origin, no network access, fullscreen. */
+function appResourceMeta(app) {
+    return {
+        ui: {
+            csp: { resourceDomains: [app.mediaOrigin], connectDomains: [] },
+            domain: app.domain,
+            prefersBorder: false,
+        },
+        'openai/ui': { preferredDisplayMode: 'fullscreen' },
+    };
+}
+// A calendar outline: 20x20, 1.33 px strokes, currentColor, transparent.
+const CALENDAR_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.33" stroke-linecap="round" stroke-linejoin="round">' +
+    '<rect x="3" y="4.5" width="14" height="12.5" rx="2.5"/>' +
+    '<path d="M3 8.5h14M7 3v3M13 3v3M6.5 11.75h1.5M9.25 11.75h1.5M12 11.75h1.5M6.5 14.25h1.5M9.25 14.25h1.5"/>' +
+    '</svg>';
+/** The entrypoint icon in tools/list. */
+export const APP_ICON = {
+    src: `data:image/svg+xml;base64,${Buffer.from(CALENDAR_SVG).toString('base64')}`,
+    mimeType: 'image/svg+xml',
+    sizes: ['any'],
+};
+let viewHtml;
+/** The built view, one self-contained HTML file (dist/view/index.html), read once. */
+export function appViewHtml() {
+    viewHtml ??= readFileSync(new URL('../view/index.html', import.meta.url), 'utf8');
+    return viewHtml;
+}
+/** Registers the view as the app's UI resource. */
+export function registerAppResource(server, app) {
+    const text = appViewHtml();
+    const _meta = appResourceMeta(app);
+    server.registerResource('postfast-calendar', APP_RESOURCE_URI, {
+        title: 'PostFast Calendar',
+        description: 'The PostFast content calendar view.',
+        mimeType: APP_RESOURCE_MIME_TYPE,
+        _meta,
+    }, async () => ({
+        contents: [{ uri: APP_RESOURCE_URI, mimeType: APP_RESOURCE_MIME_TYPE, text, _meta }],
+    }));
+}
+/**
+ * Lists icons on the named tools in tools/list. McpServer has no field for
+ * tool icons, so this wraps its tools/list handler and adds `icons` to those
+ * tools only; every other field stays the SDK's own output. If the SDK keeps
+ * its handlers elsewhere, the icons are skipped with a log and the host falls
+ * back to the app's own logo.
+ */
+export function listToolIcons(server, icons) {
+    const handlers = server.server._requestHandlers;
+    const list = handlers instanceof Map ? handlers.get('tools/list') : undefined;
+    if (!list) {
+        console.error('[postfast-mcp/core] tool icons not listed: no tools/list handler to wrap');
+        return;
+    }
+    handlers.set('tools/list', async (request, extra) => {
+        const result = (await list(request, extra));
+        for (const tool of result.tools ?? []) {
+            const toolIcons = icons.get(tool.name);
+            if (toolIcons)
+                tool.icons = toolIcons;
+        }
+        return result;
+    });
+}
+//# sourceMappingURL=app.js.map

package/dist/core/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/core/app.ts"],"names":[],"mappings":"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"}

package/dist/core/backend-port.d.ts

@@ -1,4 +1,4 @@
-import type { AnalyticsResponse, FollowerHistory, GbpLocation, PaginatedPosts, PinterestBoard, Place, Platform, SignedUploadUrl, SocialAccount, YouTubePlaylist } from './types.js';
+import type { AnalyticsResponse, AppAction, AppCalendar, AppEntrypoint, AppPostDetail, FollowerHistory, GbpLocation, PaginatedPosts, PinterestBoard, Place, Platform, SignedUploadUrl, SocialAccount, YouTubePlaylist } from './types.js';
 export interface ListPostsArgs {
     page: number;
     limit: number;
@@ -93,6 +93,27 @@ export interface UploadMediaArgs {
     data?: string;
     contentType?: string;
 }
+/** One calendar window for the app. */
+export interface AppCalendarArgs {
+    /** ISO 8601; posts whose scheduledAt is at or after this. */
+    from: string;
+    /** ISO 8601; posts whose scheduledAt is at or before this. */
+    to: string;
+    /** Most dated posts to return. */
+    limit: number;
+    /** Most undated drafts to return. */
+    draftsLimit: number;
+    entrypoint: AppEntrypoint;
+    /** True when the open view reloads; false when the app opens. */
+    refresh: boolean;
+}
+export interface AppPostArgs {
+    postId: string;
+}
+export interface AppActionArgs {
+    action: AppAction;
+    entrypoint?: AppEntrypoint;
+}
 export interface LocalUploadResult {
     key: string;
     type: 'IMAGE' | 'VIDEO';
@@ -145,4 +166,7 @@ export interface BackendPort {
     setInboxConversationStatus?(args: SetInboxConversationStatusArgs, workspaceId?: string): Promise<unknown>;
     assignInboxConversation?(args: AssignInboxConversationArgs, workspaceId?: string): Promise<unknown>;
     listTikTokSounds?(args: ListTikTokSoundsArgs, workspaceId?: string): Promise<unknown>;
+    getAppCalendar?(args: AppCalendarArgs, workspaceId?: string): Promise<AppCalendar>;
+    getAppPost?(args: AppPostArgs, workspaceId?: string): Promise<AppPostDetail>;
+    recordAppAction?(args: AppActionArgs, workspaceId?: string): Promise<unknown>;
 }

package/dist/core/build-tools.d.ts

@@ -1,5 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type AppOptions } from './app.js';
 import type { BackendPort } from './backend-port.js';
 import type { Binding, ResolvedTool } from './tool-def.js';
 export interface ConfirmGateOptions {
@@ -21,11 +22,20 @@ export interface BuildToolsOptions {
      */
     port?: BackendPort;
     /**
-     * Remote only. Holds every new post for approval and routes comment
-     * replies, private replies and deletions through prepare_inbox_action and
-     * confirm_inbox_action. When absent, the output is identical to 0.6.2.
+     * Remote only. The key that signs prepare_inbox_action / confirm_inbox_action
+     * tokens for comment replies, private replies and deletions. The remote
+     * catalogue holds every post and reply for the user's yes either way;
+     * without a key those two tools are left out (logged once), so comment
+     * replies and deletions are unavailable.
      */
     confirmGate?: ConfirmGateOptions;
+    /**
+     * Remote only. Adds the calendar app: two view-opening entrypoint tools and
+     * the view's analytics call, all hidden from the model, plus the view as a
+     * UI resource (registerCatalogTools). When absent, the output is identical
+     * to a catalog without the app.
+     */
+    app?: AppOptions;
 }
 /** Resolve the catalog for one binding: filter, flatten binding-variant fields. */
 export declare function buildTools(options: BuildToolsOptions): ResolvedTool[];
@@ -44,9 +54,14 @@ export declare function toolResult(data: unknown): CallToolResult;
 /** A business/tool error the model should see and react to (not a protocol error). */
 export declare function toolError(message: string): CallToolResult;
 /** Run a handler, converting thrown errors into `isError` tool results. */
-export declare function runTool(fn: () => Promise<unknown>): Promise<CallToolResult>;
+export declare function runTool(fn: () => Promise<unknown>, toResult?: (data: unknown) => CallToolResult): Promise<CallToolResult>;
 export interface RegisterToolsOptions extends BuildToolsOptions {
     port: BackendPort;
 }
-/** Register the resolved catalog for a binding on an MCP server. */
+/**
+ * Register the resolved catalog for a binding on an MCP server. With `app`,
+ * also registers the view as a UI resource and lists the app tools' icons,
+ * but only when a registered tool opens the view (a port without the app
+ * methods registers neither).
+ */
 export declare function registerCatalogTools(server: McpServer, options: RegisterToolsOptions): void;

package/dist/core/build-tools.js

@@ -1,16 +1,33 @@
+import { APP_RESOURCE_URI, assertAppOptions, listToolIcons, registerAppResource, } from './app.js';
 import { workspaceIdField } from './shared.js';
 import { ALL_TOOLS } from './tools/index.js';
+let warnedNoConfirmSecret = false;
 /** Resolve the catalog for one binding: filter, flatten binding-variant fields. */
 export function buildTools(options) {
-    const { binding, withWorkspaceField = false, port, confirmGate } = options;
-    const gated = binding === 'remote' && !!confirmGate;
-    if (gated && !(confirmGate.secret?.length >= 32)) {
+    const { binding, withWorkspaceField = false, port, confirmGate, app } = options;
+    const remote = binding === 'remote';
+    if (remote && confirmGate && !(confirmGate.secret?.length >= 32)) {
         throw new Error('confirmGate.secret must be at least 32 characters.');
     }
+    const secret = remote ? confirmGate?.secret : undefined;
+    if (remote && !secret && !warnedNoConfirmSecret) {
+        warnedNoConfirmSecret = true;
+        console.error('[postfast-mcp/core] no confirmGate secret: prepare_inbox_action and confirm_inbox_action are left out, so comment replies and deletions are unavailable');
+    }
+    const appOn = remote && !!app;
+    if (appOn)
+        assertAppOptions(app);
+    // Only app tools get the app options; the confirm secret goes to every tool as before.
+    const contextFor = (def) => ({
+        ...(secret ? { confirmSecret: secret } : {}),
+        ...(appOn && def.appOnly ? { app } : {}),
+    });
     return ALL_TOOLS.filter((def) => {
         if (def.binding !== 'both' && def.binding !== binding)
             return false;
-        if (gated ? def.hiddenWhenGated : def.gatedOnly)
+        if (def.needsConfirmSecret && !secret)
+            return false;
+        if (def.appOnly && !appOn)
             return false;
         if (port &&
             def.portMethod &&
@@ -20,22 +37,25 @@ export function buildTools(options) {
         }
         return true;
     }).map((def) => {
-        const inputSchema = typeof def.inputSchema === 'function' ? def.inputSchema(binding, gated) : def.inputSchema;
-        const annotations = gated && def.gatedAnnotations ? def.gatedAnnotations : def.annotations;
+        const inputSchema = typeof def.inputSchema === 'function' ? def.inputSchema(binding) : def.inputSchema;
+        const annotations = remote && def.remoteAnnotations ? def.remoteAnnotations : def.annotations;
+        const ctx = contextFor(def);
         return {
             name: def.name,
             title: def.title,
-            description: typeof def.description === 'function' ? def.description(binding, gated) : def.description,
+            description: typeof def.description === 'function' ? def.description(binding) : def.description,
             inputSchema: withWorkspaceField && def.workspaceScoped !== false
                 ? { ...inputSchema, workspaceId: workspaceIdField }
                 : inputSchema,
             annotations: { title: def.title, ...annotations },
             _meta: def._meta,
+            ...(def.icons ? { icons: def.icons } : {}),
             portMethod: def.portMethod,
-            // Gated: hand the secret to run(), also for hosts that call tool.run() themselves.
-            run: gated
-                ? (p, args, workspaceId) => def.run(p, args, workspaceId, { confirmSecret: confirmGate.secret })
+            // Hand the confirm secret and app options to run(), also for hosts that call tool.run() themselves.
+            run: Object.keys(ctx).length
+                ? (p, args, workspaceId) => def.run(p, args, workspaceId, ctx)
                 : def.run,
+            ...(def.toResult ? { toResult: def.toResult } : {}),
         };
     });
 }
@@ -69,18 +89,24 @@ export function toolError(message) {
     };
 }
 /** Run a handler, converting thrown errors into `isError` tool results. */
-export async function runTool(fn) {
+export async function runTool(fn, toResult = toolResult) {
     try {
-        return toolResult(await fn());
+        return toResult(await fn());
     }
     catch (err) {
         return toolError(err.message || 'Tool execution failed.');
     }
 }
-/** Register the resolved catalog for a binding on an MCP server. */
+/**
+ * Register the resolved catalog for a binding on an MCP server. With `app`,
+ * also registers the view as a UI resource and lists the app tools' icons,
+ * but only when a registered tool opens the view (a port without the app
+ * methods registers neither).
+ */
 export function registerCatalogTools(server, options) {
     const { port } = options;
-    for (const tool of buildTools(options)) {
+    const tools = buildTools(options);
+    for (const tool of tools) {
         server.registerTool(tool.name, {
             title: tool.title,
             description: tool.description,
@@ -90,7 +116,16 @@ export function registerCatalogTools(server, options) {
         }, (args) => runTool(() => {
             const { workspaceId, ...rest } = args ?? {};
             return tool.run(port, rest, workspaceId);
-        }));
+        }, tool.toResult));
+    }
+    const opensView = (tool) => tool._meta?.ui?.resourceUri === APP_RESOURCE_URI;
+    if (options.app && tools.some(opensView)) {
+        registerAppResource(server, options.app);
+        const icons = new Map();
+        for (const tool of tools)
+            if (tool.icons)
+                icons.set(tool.name, tool.icons);
+        listToolIcons(server, icons);
     }
 }
 //# sourceMappingURL=build-tools.js.map

package/dist/core/build-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-tools.js","sourceRoot":"","sources":["../../src/core/build-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"build-tools.js","sourceRoot":"","sources":["../../src/core/build-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/index.d.ts

@@ -4,9 +4,10 @@
  * remote host (social-schedule-mcp). Import as "postfast-mcp/core".
  */
 export * from './backend-port.js';
+export { APP_RESOURCE_MIME_TYPE, APP_RESOURCE_URI, appViewHtml, assertAppOptions, type AppOptions, } from './app.js';
 export { buildTools, registerCatalogTools, runTool, toolError, toolResult, type BuildToolsOptions, type ConfirmGateOptions, type RegisterToolsOptions, } from './build-tools.js';
 export { SERVER_INSTRUCTIONS, instructionsFor } from './instructions.js';
 export { CREATE_APPROVAL_STATUSES, CREATE_STATUSES, IMAGE_MIME_TYPES, PLATFORMS, POST_STATUSES, SET_APPROVAL_STATUSES, VIDEO_MIME_TYPES, jsonParse, workspaceIdField, } from './shared.js';
-export type { Binding, ResolvedTool, ResolvedToolAnnotations, ToolAnnotations, ToolDef, } from './tool-def.js';
+export type { Binding, ResolvedTool, ResolvedToolAnnotations, ToolAnnotations, ToolDef, ToolIcon, } from './tool-def.js';
 export { ALL_TOOLS } from './tools/index.js';
 export * from './types.js';

package/dist/core/index.js

@@ -4,6 +4,7 @@
  * remote host (social-schedule-mcp). Import as "postfast-mcp/core".
  */
 export * from './backend-port.js';
+export { APP_RESOURCE_MIME_TYPE, APP_RESOURCE_URI, appViewHtml, assertAppOptions, } from './app.js';
 export { buildTools, registerCatalogTools, runTool, toolError, toolResult, } from './build-tools.js';
 export { SERVER_INSTRUCTIONS, instructionsFor } from './instructions.js';
 export { CREATE_APPROVAL_STATUSES, CREATE_STATUSES, IMAGE_MIME_TYPES, PLATFORMS, POST_STATUSES, SET_APPROVAL_STATUSES, VIDEO_MIME_TYPES, jsonParse, workspaceIdField, } from './shared.js';

package/dist/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,OAAO,EACP,SAAS,EACT,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,GAEjB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,UAAU,EACV,oBAAoB,EACpB,OAAO,EACP,SAAS,EACT,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EACL,wBAAwB,EACxB,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AASrB,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,cAAc,YAAY,CAAC"}

package/dist/core/instructions.d.ts

@@ -1,5 +1,10 @@
 import type { Binding } from './tool-def.js';
 export declare const SERVER_INSTRUCTIONS: Record<Binding, string>;
-export declare function instructionsFor(binding: Binding, opts?: {
+/**
+ * The server instructions for a binding. The remote text is always the one
+ * that holds posts and replies for the user's yes; `opts` is accepted for
+ * hosts written against 0.8 and earlier, and ignored.
+ */
+export declare function instructionsFor(binding: Binding, _opts?: {
     gated?: boolean;
 }): string;

package/dist/core/instructions.js

@@ -4,17 +4,17 @@
  * backend's actual create-posts validation, so it matches what the API
  * enforces (prevents the model discovering rules by failing).
  *
- * The two bindings differ only where their tool surfaces differ: workspace
- * switching and conversation-media/URL uploads exist on the remote host, the
- * stdio bin uploads local files instead.
+ * The two bindings share most paragraphs. They differ where their tool
+ * surfaces differ (workspace switching and conversation-media/URL uploads on
+ * the remote host, local files on stdio) and in how posts and comment replies
+ * go out: on the remote binding every post is held until approve_posts, and
+ * replies and comment deletions go through prepare_inbox_action and
+ * confirm_inbox_action, each only after the user says yes.
  */
-const SHARED_TAIL = `Before scheduling, confirm the target account's connectionStatus is CONNECTED. A DISABLED account will not publish (disconnected accounts are the #1 cause of failed posts) — saving a DRAFT is still allowed.
-
-Status & timing: status=SCHEDULED requires scheduledAt on every post (ISO-8601, in the future, within 1 year); status=DRAFT must omit scheduledAt. approvalStatus=APPROVED publishes; PENDING_APPROVAL holds it for review. There is no instant "publish now" — for an immediate post, set scheduledAt a few minutes ahead of now (a time at or before the current moment is rejected).
-
-Media: use the key returned by an upload tool, and set mediaItems[].type to match the file (IMAGE for image/* keys, VIDEO for video/* keys — a mismatch is rejected). Videos are capped at 250MB (Telegram 50MB, Bluesky 100MB). Media is REQUIRED on TikTok, YouTube (video only), Instagram, and Pinterest; X, LinkedIn, Facebook, Threads, Bluesky, Telegram, and Google Business Profile allow text-only posts (GBP accepts 1 image and no video). This requirement applies even to DRAFTS — a draft to a media-required platform without media is rejected. So if the user asks to post to a media-required platform and provides no media, ask them for an image/video (or generate and upload one) BEFORE calling create_posts; don't attempt the post without media.
-
-Per-platform limits (media counts / characters):
+const INTRO = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.`;
+const CONNECTED = `Before scheduling, confirm the target account's connectionStatus is CONNECTED. A DISABLED account will not publish (disconnected accounts are the #1 cause of failed posts) — saving a DRAFT is still allowed.`;
+const MEDIA = `Media: use the key returned by an upload tool, and set mediaItems[].type to match the file (IMAGE for image/* keys, VIDEO for video/* keys — a mismatch is rejected). Videos are capped at 250MB (Telegram 50MB, Bluesky 100MB). Media is REQUIRED on TikTok, YouTube (video only), Instagram, and Pinterest; X, LinkedIn, Facebook, Threads, Bluesky, Telegram, and Google Business Profile allow text-only posts (GBP accepts 1 image and no video). This requirement applies even to DRAFTS — a draft to a media-required platform without media is rejected. So if the user asks to post to a media-required platform and provides no media, ask them for an image/video (or generate and upload one) BEFORE calling create_posts; don't attempt the post without media.`;
+const LIMITS = `Per-platform limits (media counts / characters):
 - X: up to 4 images or 1 video (no mixing); 280 chars (4,000 with X Premium).
 - TikTok: 1 video OR up to 10 images; 4,000 chars.
 - Instagram: up to 10 media items, images and videos mixed; 2,200 chars, max 30 hashtags.
@@ -23,11 +23,10 @@ Per-platform limits (media counts / characters):
 - Threads: up to 10 media items, images and videos mixed; 500 chars.
 - Pinterest: up to 5 images or 1 video; title max 100, description max 800.
 - Google Business Profile: text only, or 1 image and no video; 1,500 chars.
-- Bluesky: up to 4 images or 1 video. Telegram: up to 10 media items, at most 3 of them videos.
+- Bluesky: up to 10 images or 1 video. Telegram: up to 10 media items, at most 3 of them videos.
 No post carries more than 10 media items.
-If content exceeds the target platform's character limit, don't schedule it as-is — tell the user and offer to shorten or split it (X is 280 unless the account has X Premium = 4,000).
-
-Platform-specific options go in the controls object, e.g.:
+If content exceeds the target platform's character limit, don't schedule it as-is — tell the user and offer to shorten or split it (X is 280 unless the account has X Premium = 4,000).`;
+const CONTROLS = `Platform-specific options go in the controls object, e.g.:
 - Pinterest: controls.pinterestBoardId is REQUIRED — it is a board's boardId from list_pinterest_boards, NOT the Pinterest account's socialMediaId.
 - Google Business Profile: controls.gbpLocationId is required — the locationId from list_gbp_locations.
 - YouTube: controls.youtubePlaylistId is the playlistId from list_youtube_playlists; youtubeIsShort defaults true; title falls back to the first 100 chars of content.
@@ -37,56 +36,46 @@ Platform-specific options go in the controls object, e.g.:
 - Geotag a place (Facebook/Instagram): call search_places, then pass a returned id as controls.facebookPlaceId (Facebook feed posts only — not Reels/Stories/video) and/or controls.instagramLocationId (Instagram single media only — not carousels). One id works for both.
 - LinkedIn: attach a document via controls.linkedinAttachmentKey.
 - X: controls.xRetweetUrl reposts an existing tweet (content/media are ignored).
-Note: list_pinterest_boards / list_youtube_playlists / list_gbp_locations take the account's socialMediaId; each returned item has BOTH an internal id and the platform id (boardId / playlistId / locationId) — pass the PLATFORM id to controls, not the internal id or the account id.
-
-Failed posts carry lastError — usually a disconnected account (reconnect, then retry) or platform-rejected media.
-
-delete_post removes a post from PostFast only — it never deletes an already-published post from the social platform. Say so when a user asks to delete something that has already gone out.
-
-Social inbox (comments on your posts — TikTok, Instagram, Facebook Pages, Threads; an account's inboxCapable flag from list_accounts says what is live today): read with list_inbox_conversations → list_inbox_items (get_inbox_unread_count for the total), reply with reply_to_inbox_item (public, under a specific comment item) or send_inbox_private_reply (Instagram only: one per comment, within 7 days). Whether and how long a reply can be comes ONLY from the conversation's server-computed canReply / maxReplyLength / windowState / disabledReason — never assume platform rules. Moderate with set_inbox_item_state (HIDE / UNHIDE / DELETE — DELETE removes the comment on the platform and cannot be undone), triage with set_inbox_conversation_status and assign_inbox_conversation, and call mark_inbox_conversation_read after presenting a thread. It is a comments inbox — never present it as DMs or messages.`;
-const STDIO_INSTRUCTIONS = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.
-
-Flow: list_accounts to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_media (a local file, by absolute path) or get_upload_urls (signed PUT upload for raw bytes) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.
-
-The POSTFAST_API_KEY is workspace-scoped — every tool acts in that workspace.
-
-${SHARED_TAIL}`;
-const REMOTE_INSTRUCTIONS = `PostFast schedules and publishes social posts across X, Instagram, Facebook, TikTok, LinkedIn, YouTube, Threads, Pinterest, Bluesky, Telegram, and Google Business Profile.
-
-Flow: list_accounts (+ list_workspaces) to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_from_url (a public https URL) or upload_media (a ChatGPT-attached/generated image, or base64) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.
-
-Workspaces: omit workspaceId to use the connection's default; pass a workspaceId (from list_workspaces) to act in another workspace.
-
-${SHARED_TAIL}`;
+Note: list_pinterest_boards / list_youtube_playlists / list_gbp_locations take the account's socialMediaId; each returned item has BOTH an internal id and the platform id (boardId / playlistId / locationId) — pass the PLATFORM id to controls, not the internal id or the account id.`;
+const FAILED = `Failed posts carry lastError — usually a disconnected account (reconnect, then retry) or platform-rejected media.`;
+const DELETE_POST = `delete_post removes a post from PostFast only — it never deletes an already-published post from the social platform. Say so when a user asks to delete something that has already gone out.`;
+const REMOTE_DELETE_POST = `${DELETE_POST} Deleting can't be undone, so show the user which post (account, time, first line) and call delete_post only after they say yes in the conversation.`;
+const STDIO_INSTRUCTIONS = [
+    INTRO,
+    `Flow: list_accounts to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_media (a local file, by absolute path) or get_upload_urls (signed PUT upload for raw bytes) → a post publishes when status=SCHEDULED and approvalStatus=APPROVED.`,
+    `The POSTFAST_API_KEY is workspace-scoped — every tool acts in that workspace.`,
+    CONNECTED,
+    `Status & timing: status=SCHEDULED requires scheduledAt on every post (ISO-8601, in the future, within 1 year); status=DRAFT must omit scheduledAt. approvalStatus=APPROVED publishes; PENDING_APPROVAL holds it for review. There is no instant "publish now" — for an immediate post, set scheduledAt a few minutes ahead of now (a time at or before the current moment is rejected).`,
+    MEDIA,
+    LIMITS,
+    CONTROLS,
+    FAILED,
+    DELETE_POST,
+    `Social inbox (comments on your posts — TikTok, Instagram, Facebook Pages, Threads; an account's inboxCapable flag from list_accounts says what is live today): read with list_inbox_conversations → list_inbox_items (get_inbox_unread_count for the total), reply with reply_to_inbox_item (public, under a specific comment item) or send_inbox_private_reply (Instagram only: one per comment, within 7 days). Whether and how long a reply can be comes ONLY from the conversation's server-computed canReply / maxReplyLength / windowState / disabledReason — never assume platform rules. Moderate with set_inbox_item_state (HIDE / UNHIDE / DELETE — DELETE removes the comment on the platform and cannot be undone), triage with set_inbox_conversation_status and assign_inbox_conversation, and call mark_inbox_conversation_read after presenting a thread. It is a comments inbox — never present it as DMs or messages.`,
+].join('\n\n');
+const REMOTE_INSTRUCTIONS = [
+    INTRO,
+    `Flow: list_accounts (+ list_workspaces) to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_from_url (a public https URL) or upload_media (base64 bytes in data + contentType). Posts are held for approval and nothing publishes until approve_posts sets them to APPROVED: show the user what will be posted, where and when, and call approve_posts only after they say yes, even if they asked you to post it.`,
+    `Workspaces: omit workspaceId to use the connection's default; pass a workspaceId (from list_workspaces) to act in another workspace.`,
+    CONNECTED,
+    `Status & timing: status=SCHEDULED requires scheduledAt on every post (ISO-8601, in the future, within 1 year); status=DRAFT must omit scheduledAt. Every post is created as PENDING_APPROVAL and publishes at its scheduledAt only once approve_posts sets it to APPROVED.`,
+    MEDIA,
+    LIMITS,
+    CONTROLS,
+    FAILED,
+    REMOTE_DELETE_POST,
+    `Social inbox (comments on your posts: TikTok, Instagram, Facebook Pages, Threads; an account's inboxCapable flag from list_accounts says what is live today): read with list_inbox_conversations → list_inbox_items (get_inbox_unread_count for the total). To reply publicly under a comment (REPLY), send an Instagram private reply (PRIVATE_REPLY: one per comment, within 7 days) or delete a comment permanently (DELETE), call prepare_inbox_action, show the user the preview, and carry it out with confirm_inbox_action only after they say yes, even if they gave you the text. Whether and how long a reply can be comes ONLY from the conversation's server-computed canReply / maxReplyLength / windowState / disabledReason; never assume platform rules. Hide or restore a comment with set_inbox_item_state (HIDE / UNHIDE), triage with set_inbox_conversation_status and assign_inbox_conversation, and call mark_inbox_conversation_read after presenting a thread. It is a comments inbox; never present it as DMs or messages.`,
+].join('\n\n');
 export const SERVER_INSTRUCTIONS = {
     stdio: STDIO_INSTRUCTIONS,
     remote: REMOTE_INSTRUCTIONS,
 };
 /**
- * The remote text for a host with the confirm gate on: REMOTE_INSTRUCTIONS
- * with the paragraphs starting with these prefixes swapped, so the ungated
- * text above is never touched.
+ * The server instructions for a binding. The remote text is always the one
+ * that holds posts and replies for the user's yes; `opts` is accepted for
+ * hosts written against 0.8 and earlier, and ignored.
  */
-const GATED_PARAGRAPHS = [
-    [
-        'Flow: ',
-        "Flow: list_accounts (+ list_workspaces) to see what's connected → create_posts (one socialMediaId per post; batch up to 15) → attach media via upload_from_url (a public https URL) or upload_media (base64 bytes in data + contentType). Posts are held for approval and nothing publishes until approve_posts sets them to APPROVED: show the user what will be posted, where and when, and call approve_posts only after they say yes, even if they asked you to post it.",
-    ],
-    [
-        'Status & timing: ',
-        'Status & timing: status=SCHEDULED requires scheduledAt on every post (ISO-8601, in the future, within 1 year); status=DRAFT must omit scheduledAt. Every post is created as PENDING_APPROVAL and publishes at its scheduledAt only once approve_posts sets it to APPROVED.',
-    ],
-    [
-        'Social inbox ',
-        "Social inbox (comments on your posts: TikTok, Instagram, Facebook Pages, Threads; an account's inboxCapable flag from list_accounts says what is live today): read with list_inbox_conversations → list_inbox_items (get_inbox_unread_count for the total). To reply publicly under a comment (REPLY), send an Instagram private reply (PRIVATE_REPLY: one per comment, within 7 days) or delete a comment permanently (DELETE), call prepare_inbox_action, show the user the preview, and carry it out with confirm_inbox_action only after they say yes, even if they gave you the text. Whether and how long a reply can be comes ONLY from the conversation's server-computed canReply / maxReplyLength / windowState / disabledReason; never assume platform rules. Hide or restore a comment with set_inbox_item_state (HIDE / UNHIDE), triage with set_inbox_conversation_status and assign_inbox_conversation, and call mark_inbox_conversation_read after presenting a thread. It is a comments inbox; never present it as DMs or messages.",
-    ],
-];
-const GATED_REMOTE_INSTRUCTIONS = REMOTE_INSTRUCTIONS.split('\n\n')
-    .map((paragraph) => GATED_PARAGRAPHS.find(([prefix]) => paragraph.startsWith(prefix))?.[1] ?? paragraph)
-    .join('\n\n');
-export function instructionsFor(binding, opts) {
-    if (binding === 'remote' && opts?.gated)
-        return GATED_REMOTE_INSTRUCTIONS;
+export function instructionsFor(binding, _opts) {
     return SERVER_INSTRUCTIONS[binding];
 }
 //# sourceMappingURL=instructions.js.map

package/dist/core/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/core/instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;w4BAmCo3B,CAAC;AAEz4B,MAAM,kBAAkB,GAAG;;;;;;EAMzB,WAAW,EAAE,CAAC;AAEhB,MAAM,mBAAmB,GAAG;;;;;;EAM1B,WAAW,EAAE,CAAC;AAEhB,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,gBAAgB,GAAqC;IACzD;QACE,QAAQ;QACR,8cAA8c;KAC/c;IACD;QACE,mBAAmB;QACnB,4QAA4Q;KAC7Q;IACD;QACE,eAAe;QACf,s/BAAs/B;KACv/B;CACF,CAAC;AAEF,MAAM,yBAAyB,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,CAAC;KAChE,GAAG,CACF,CAAC,SAAS,EAAE,EAAE,CACZ,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,SAAS,CACtF;KACA,IAAI,CAAC,MAAM,CAAC,CAAC;AAEhB,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,IAA0B;IAC1E,IAAI,OAAO,KAAK,QAAQ,IAAI,IAAI,EAAE,KAAK;QAAE,OAAO,yBAAyB,CAAC;IAC1E,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/core/instructions.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,MAAM,KAAK,GAAG,6KAA6K,CAAC;AAE5L,MAAM,SAAS,GAAG,gNAAgN,CAAC;AAEnO,MAAM,KAAK,GAAG,8uBAA8uB,CAAC;AAE7vB,MAAM,MAAM,GAAG;;;;;;;;;;;wLAWyK,CAAC;AAEzL,MAAM,QAAQ,GAAG;;;;;;;;;;0RAUyQ,CAAC;AAE3R,MAAM,MAAM,GAAG,mHAAmH,CAAC;AAEnI,MAAM,WAAW,GAAG,6LAA6L,CAAC;AAElN,MAAM,kBAAkB,GAAG,GAAG,WAAW,sJAAsJ,CAAC;AAEhM,MAAM,kBAAkB,GAAG;IACzB,KAAK;IACL,qSAAqS;IACrS,+EAA+E;IAC/E,SAAS;IACT,yXAAyX;IACzX,KAAK;IACL,MAAM;IACN,QAAQ;IACR,MAAM;IACN,WAAW;IACX,y4BAAy4B;CAC14B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEf,MAAM,mBAAmB,GAAG;IAC1B,KAAK;IACL,8cAA8c;IAC9c,sIAAsI;IACtI,SAAS;IACT,4QAA4Q;IAC5Q,KAAK;IACL,MAAM;IACN,QAAQ;IACR,MAAM;IACN,kBAAkB;IAClB,s/BAAs/B;CACv/B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAEf,MAAM,CAAC,MAAM,mBAAmB,GAA4B;IAC1D,KAAK,EAAE,kBAAkB;IACzB,MAAM,EAAE,mBAAmB;CAC5B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB,EAAE,KAA2B;IAC3E,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;AACtC,CAAC"}