@postplus/cli 0.1.46 → 0.1.47

package/build/authed-cloud-request.d.ts

@@ -0,0 +1,39 @@
+export type AuthedCloudRequestAuth = {
+    apiBaseUrl: string;
+    cliSessionToken: string;
+};
+export type AuthedCloudRequestInput = {
+    auth: AuthedCloudRequestAuth;
+    pathName: string;
+    method?: 'GET' | 'POST';
+    /**
+     * Parsed JSON body. When provided the request sends `content-type:
+     * application/json` and the serialized body; when omitted neither is sent.
+     */
+    body?: unknown;
+    skillName?: string | null;
+    /**
+     * In-process override for the skills release id header. When provided (the
+     * hosted-lib path) it is stamped verbatim and the disk config is NOT read for
+     * the release id; when omitted (the bin path) the release id comes from
+     * `readLocalConfig()` as before.
+     */
+    skillsReleaseId?: string | null;
+    timeoutMs?: number;
+    /**
+     * Optional once-only 401 refresh. When provided, a `401` response triggers a
+     * single retry: `refreshAuth()` returns fresh credentials and the request is
+     * re-issued once with them. When omitted, the first response is returned
+     * verbatim (the caller keeps its own `!ok` interpretation either way).
+     */
+    retryOn401?: () => Promise<AuthedCloudRequestAuth>;
+};
+/**
+ * Single transport envelope for every authenticated PostPlus Cloud request:
+ * canonical header set (`accept` + compatibility headers + `Bearer` token +
+ * optional `content-type`), `AbortSignal.timeout`, and an optional once-only
+ * 401-refresh-retry. It returns the raw `Response` so each caller keeps its own
+ * `!ok` interpretation — this is a narrow transport primitive, not a request
+ * framework.
+ */
+export declare function sendAuthedCloudRequest(input: AuthedCloudRequestInput): Promise<Response>;

package/build/authed-cloud-request.js

@@ -19,6 +19,9 @@ export async function sendAuthedCloudRequest(input) {
 async function issueAuthedCloudRequest(auth, input) {
     const compatibilityHeaders = await buildPostPlusClientCompatibilityHeaders({
         skillName: input.skillName ?? null,
+        ...(input.skillsReleaseId !== undefined
+            ? { skillsReleaseId: input.skillsReleaseId }
+            : {}),
     });
     const hasBody = input.body !== undefined;
     const headers = {

package/build/client-compatibility.js

@@ -14,16 +14,19 @@ export const POSTPLUS_CLIENT_COMPATIBILITY_HEADERS = {
     skillName: 'x-postplus-skill-name',
 };
 export async function buildPostPlusClientCompatibilityHeaders(input = {}) {
+    const hasReleaseIdOverride = input.skillsReleaseId !== undefined;
     const [cliVersion, config] = await Promise.all([
         readCurrentCliVersion(),
-        readLocalConfig(),
+        hasReleaseIdOverride ? Promise.resolve(null) : readLocalConfig(),
     ]);
     const headers = {
         [POSTPLUS_CLIENT_COMPATIBILITY_HEADERS.cliVersion]: cliVersion,
         [POSTPLUS_CLIENT_COMPATIBILITY_HEADERS.contractVersion]: String(POSTPLUS_CLIENT_CONTRACT_VERSION),
         [POSTPLUS_CLIENT_COMPATIBILITY_HEADERS.runtime]: POSTPLUS_CLIENT_RUNTIME,
     };
-    const skillsReleaseId = config?.managedSkills?.releaseId?.trim();
+    const skillsReleaseId = hasReleaseIdOverride
+        ? input.skillsReleaseId?.trim()
+        : config?.managedSkills?.releaseId?.trim();
     const skillName = input.skillName?.trim();
     if (skillsReleaseId) {
         headers[POSTPLUS_CLIENT_COMPATIBILITY_HEADERS.skillsReleaseId] =

package/build/generated/hosted-execution-manifest.generated.js

@@ -1138,23 +1138,20 @@ export const HOSTED_EXECUTION_MANIFESTS = {
                             "required": true
                         },
                         {
-                            "name": "width_and_height",
-                            "class": "intent",
-                            "flag": "--width-and-height",
-                            "type": "string",
-                            "required": true
-                        },
-                        {
-                            "name": "quality",
+                            "name": "aspect_ratio",
                             "class": "default",
-                            "flag": "--quality",
+                            "flag": "--aspect-ratio",
                             "type": "string",
                             "enumValues": [
-                                "720p",
-                                "1080p"
+                                "9:16",
+                                "16:9",
+                                "4:3",
+                                "3:4",
+                                "1:1",
+                                "2:3",
+                                "3:2"
                             ],
-                            "canonicalize": "lowercase",
-                            "default": "720p",
+                            "default": "1:1",
                             "required": false
                         },
                         {
@@ -1201,7 +1198,7 @@ export const HOSTED_EXECUTION_MANIFESTS = {
                         }
                     ],
                     "billingDimensions": [
-                        "quality"
+                        "billableUnitCount"
                     ]
                 }
             ]
@@ -1261,6 +1258,8 @@ export const HOSTED_EXECUTION_MANIFESTS = {
             "capability": "media-generation",
             "endpointKeys": [
                 "video-seedance-2-image",
+                "video-seedance-2-mini-image",
+                "video-seedance-2-mini-text",
                 "video-seedance-2-text"
             ],
             "endpoints": [
@@ -1336,6 +1335,200 @@ export const HOSTED_EXECUTION_MANIFESTS = {
                         "referenceVideoMode"
                     ]
                 },
+                {
+                    "endpointKey": "video-seedance-2-mini-image",
+                    "provider": "wavespeed",
+                    "providerModelPath": "bytedance/seedance-2.0-mini/image-to-video",
+                    "fields": [
+                        {
+                            "name": "prompt",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "string",
+                            "required": true
+                        },
+                        {
+                            "name": "image",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "media-url",
+                            "required": true
+                        },
+                        {
+                            "name": "resolution",
+                            "class": "default",
+                            "flag": null,
+                            "type": "string",
+                            "enumValues": [
+                                "480p",
+                                "720p",
+                                "1080p",
+                                "4k"
+                            ],
+                            "canonicalize": "lowercase",
+                            "default": "720p",
+                            "required": false
+                        },
+                        {
+                            "name": "duration",
+                            "class": "default",
+                            "flag": null,
+                            "type": "number",
+                            "default": 5,
+                            "required": false,
+                            "min": 4,
+                            "max": 15
+                        },
+                        {
+                            "name": "operationId",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        },
+                        {
+                            "name": "quoteConfirmationToken",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        },
+                        {
+                            "name": "requestDimensions",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        }
+                    ],
+                    "billingDimensions": [
+                        "duration",
+                        "resolution",
+                        "referenceVideoCount",
+                        "referenceVideoMode"
+                    ]
+                },
+                {
+                    "endpointKey": "video-seedance-2-mini-text",
+                    "provider": "wavespeed",
+                    "providerModelPath": "bytedance/seedance-2.0-mini/text-to-video",
+                    "fields": [
+                        {
+                            "name": "prompt",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "string",
+                            "required": true
+                        },
+                        {
+                            "name": "resolution",
+                            "class": "default",
+                            "flag": null,
+                            "type": "string",
+                            "enumValues": [
+                                "480p",
+                                "720p",
+                                "1080p",
+                                "4k"
+                            ],
+                            "canonicalize": "lowercase",
+                            "default": "720p",
+                            "required": false
+                        },
+                        {
+                            "name": "aspect_ratio",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "string",
+                            "enumValues": [
+                                "21:9",
+                                "16:9",
+                                "4:3",
+                                "1:1",
+                                "3:4",
+                                "9:16"
+                            ],
+                            "required": false
+                        },
+                        {
+                            "name": "duration",
+                            "class": "default",
+                            "flag": null,
+                            "type": "number",
+                            "default": 5,
+                            "required": false,
+                            "min": 4,
+                            "max": 15
+                        },
+                        {
+                            "name": "reference_images",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "media-url",
+                            "repeatable": true,
+                            "required": false
+                        },
+                        {
+                            "name": "reference_videos",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "media-url",
+                            "repeatable": true,
+                            "required": false
+                        },
+                        {
+                            "name": "reference_audios",
+                            "class": "intent",
+                            "flag": null,
+                            "type": "media-url",
+                            "repeatable": true,
+                            "required": false
+                        },
+                        {
+                            "name": "enable_web_search",
+                            "class": "default",
+                            "flag": null,
+                            "type": "boolean",
+                            "default": false,
+                            "required": false
+                        },
+                        {
+                            "name": "generate_audio",
+                            "class": "default",
+                            "flag": null,
+                            "type": "boolean",
+                            "default": true,
+                            "required": false
+                        },
+                        {
+                            "name": "operationId",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        },
+                        {
+                            "name": "quoteConfirmationToken",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        },
+                        {
+                            "name": "requestDimensions",
+                            "class": "runner-managed",
+                            "flag": null,
+                            "type": "string",
+                            "required": false
+                        }
+                    ],
+                    "billingDimensions": [
+                        "duration",
+                        "resolution",
+                        "referenceVideoCount",
+                        "referenceVideoMode"
+                    ]
+                },
                 {
                     "endpointKey": "video-seedance-2-text",
                     "provider": "wavespeed",

package/build/hosted-domain-commands.d.ts

@@ -0,0 +1,14 @@
+import { type AuthedCloudRequestAuth } from './authed-cloud-request.js';
+import { type HostedDomain } from './hosted-manifest-index.js';
+export type HostedRequestContext = {
+    auth: AuthedCloudRequestAuth;
+    skillsReleaseId?: string;
+    /**
+     * The request-json envelope injected in place of a `--request <file>` read.
+     * Surfaces that need a body assert it is present and the right shape (object vs
+     * array) exactly as the file-read path validated the parsed file contents.
+     */
+    requestJson?: Record<string, unknown> | unknown[];
+};
+export declare function runHostedDomainCommand(domain: HostedDomain, args: string[], context?: HostedRequestContext): Promise<number | unknown>;
+export declare function runMediaFileCommand(args: string[], context?: HostedRequestContext): Promise<number | unknown>;

package/build/hosted-domain-commands.js

@@ -3,7 +3,7 @@ import { createReadStream } from 'node:fs';
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { resolveFreshRemoteAuth } from './auth-session.js';
-import { sendAuthedCloudRequest } from './authed-cloud-request.js';
+import { sendAuthedCloudRequest, } from './authed-cloud-request.js';
 import { formatPostPlusCompatibilityError } from './client-compatibility.js';
 import { assertModelledFieldValuesInRange } from './hosted-field-validation.js';
 import { buildVerbTargetIndex, } from './hosted-manifest-index.js';
@@ -27,6 +27,20 @@ function buildPublishVerbIndex() {
     }
     return index;
 }
+// Reads the request-json body for a surface: from the injected object (lib path)
+// or by reading `--request <file>` (bin path). This is the SINGLE place the two
+// paths diverge on input source; the resolved body then flows through the SAME
+// validation + envelope build, so the URL/body/headers stay byte-identical.
+async function resolveRequestBody(context, flags) {
+    if (context) {
+        if (context.requestJson === undefined) {
+            throw new Error('This hosted command requires a requestJson body.');
+        }
+        return { body: context.requestJson, errorInputLabel: 'requestJson' };
+    }
+    const requestPath = requireFlag(flags, 'request');
+    return { body: await readJsonFile(requestPath), errorInputLabel: requestPath };
+}
 class HostedQuoteConfirmationRequiredError extends Error {
     challenge;
     constructor(message, challenge) {
@@ -43,41 +57,45 @@ class HostedProductRequestError extends Error {
         this.name = 'HostedProductRequestError';
     }
 }
-export async function runHostedDomainCommand(domain, args) {
+export async function runHostedDomainCommand(domain, args, 
+// Present only on the in-process hosted-lib path; the bin path never passes it.
+// See HostedRequestContext: it carries the injected auth/releaseId/requestJson
+// and switches every leaf onto the no-disk, no-file, return-payload behavior.
+context) {
     const [subcommand, ...rest] = args;
     if (domain === 'research') {
         if (subcommand === 'schema') {
-            return runHostedSchema(domain, rest);
+            return runHostedSchema(domain, rest, context);
         }
         if (subcommand === 'collect') {
-            return runResearchCollect(rest);
+            return runResearchCollect(rest, context);
         }
         if (subcommand === 'scrape') {
-            return runResearchScrape(rest);
+            return runResearchScrape(rest, context);
         }
         printResearchHelp();
         return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
     }
     if (subcommand === 'schema') {
-        return runHostedSchema(domain, rest);
+        return runHostedSchema(domain, rest, context);
     }
     // Poll a pending async media-generation run by handle. This is a hand-coded
     // branch (not a manifest verb) because a status poll has no endpointKey/field
     // contract to project — exactly like the `research collect --run-handle`
     // polling branch. It must be checked before the manifest verb dispatch.
     if (domain === 'media' && subcommand === 'poll') {
-        return runMediaPoll(rest);
+        return runMediaPoll(rest, context);
     }
     if (domain === 'media' &&
         subcommand &&
         MEDIA_VERB_ENDPOINTS.has(subcommand)) {
-        return runMediaVerb(subcommand, rest);
+        return runMediaVerb(subcommand, rest, context);
     }
     // publish: the OPERATION is the subcommand (no separate target positional).
     if (domain === 'publish' &&
         subcommand &&
         PUBLISH_VERB_OPERATIONS.has(subcommand)) {
-        return runPublishOperation(subcommand, rest);
+        return runPublishOperation(subcommand, rest, context);
     }
     printDomainVerbHelp(domain);
     return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
@@ -87,7 +105,7 @@ export async function runHostedDomainCommand(domain, args) {
 // scalar intent/default fields to flags, a request-json surface reads the nested
 // envelope from `--request <file>`. Either way runner-managed fields (billing
 // dimensions, ids, tokens) are derived/minted by the runner, never agent-supplied.
-async function runMediaVerb(verb, args) {
+async function runMediaVerb(verb, args, context) {
     const targets = MEDIA_VERB_ENDPOINTS.get(verb);
     if (!targets) {
         throw new Error(`Unknown media verb ${verb}.`);
@@ -112,6 +130,7 @@ async function runMediaVerb(verb, args) {
             modelKey: targetKey,
             resolved,
             verb,
+            context,
         });
     }
     if (resolved.surface === 'request-json') {
@@ -120,6 +139,7 @@ async function runMediaVerb(verb, args) {
             endpointKey: targetKey,
             resolved,
             verb,
+            context,
         });
     }
     return runMediaVerbFlags({
@@ -127,12 +147,13 @@ async function runMediaVerb(verb, args) {
         endpointKey: targetKey,
         resolved,
         verb,
+        context,
     });
 }
 // Flags surface (e.g. audio-transcription): scalar intent/default fields map to
 // flags; runner-managed fields have no flag so the agent cannot pass them.
 async function runMediaVerbFlags(args) {
-    const { endpointKey, resolved, verb } = args;
+    const { endpointKey, resolved, verb, context } = args;
     const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
     const fields = endpoint.fields;
     const flagToField = new Map();
@@ -193,6 +214,7 @@ async function runMediaVerbFlags(args) {
         outputPath,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
         skillName: flags.values.get('skill') ?? resolved.skill,
+        context,
     });
 }
 // Request-json surface (e.g. seedance-submitter): the nested envelope is supplied
@@ -200,7 +222,7 @@ async function runMediaVerbFlags(args) {
 // so the body carries only the media-generation input. Runner-managed fields have
 // no flag and must not appear in the body — the CLI fast-fails if they do.
 async function runMediaVerbRequestJson(args) {
-    const { endpointKey, resolved, verb } = args;
+    const { endpointKey, resolved, verb, context } = args;
     const endpoint = requireResolvedEndpoint(resolved, verb, endpointKey);
     const flags = parseFlags(args.args, new Set(['json']));
     const allowedKeys = new Set([
@@ -216,9 +238,8 @@ async function runMediaVerbRequestJson(args) {
             throw new Error(`Unknown option for media ${verb}: --${key}.`);
         }
     }
-    const requestPath = requireFlag(flags, 'request');
     const outputPath = flags.values.get('output') ?? null;
-    const raw = await readJsonFile(requestPath);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`media ${verb} ${endpointKey} --request must be a JSON object of media-generation input.`);
     }
@@ -239,7 +260,7 @@ async function runMediaVerbRequestJson(args) {
     return submitMediaGenerationRequest({
         capability: resolved.capability,
         endpointKey,
-        errorInputLabel: requestPath,
+        errorInputLabel,
         input,
         json: flags.booleans.has('json'),
         operationId: flags.values.get('hosted-operation-id') ??
@@ -247,6 +268,7 @@ async function runMediaVerbRequestJson(args) {
         outputPath,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token'),
         skillName: flags.values.get('skill') ?? resolved.skill,
+        context,
     });
 }
 function requireResolvedEndpoint(resolved, verb, endpointKey) {
@@ -264,7 +286,7 @@ function requireResolvedEndpoint(resolved, verb, endpointKey) {
 // `estimatedUsage.videoSeconds` so the Web boundary can route eligible short
 // videos through its preflight/routing path (omit it to use the default route).
 async function runVideoAnalysisVerb(args) {
-    const { modelKey, resolved, verb } = args;
+    const { modelKey, resolved, verb, context } = args;
     const flags = parseFlags(args.args, new Set(['json']));
     const allowedKeys = new Set([
         'hosted-operation-id',
@@ -280,9 +302,8 @@ async function runVideoAnalysisVerb(args) {
             throw new Error(`Unknown option for media ${verb}: --${key}.`);
         }
     }
-    const requestPath = requireFlag(flags, 'request');
     const outputPath = flags.values.get('output') ?? null;
-    const raw = await readJsonFile(requestPath);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`media ${verb} ${modelKey} --request must be a JSON object of Gemini request payload.`);
     }
@@ -311,16 +332,17 @@ async function runVideoAnalysisVerb(args) {
             `postplus-cli:media:video-analysis:analyze:${randomUUID()}`,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body,
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: flags.values.get('skill') ?? resolved.skill,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // `media-file upload`: the generic local-file -> hosted media verb. Released
 // skills ship no scripts, so a skill that must place a local file behind hosted
@@ -346,15 +368,15 @@ function inferUploadMimeType(filePath) {
     return (MEDIA_FILE_MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] ??
         'application/octet-stream');
 }
-export async function runMediaFileCommand(args) {
+export async function runMediaFileCommand(args, context) {
     const [subcommand, ...rest] = args;
     if (subcommand === 'upload') {
-        return runMediaFileUpload(rest);
+        return runMediaFileUpload(rest, context);
     }
     printMediaFileHelp();
     return subcommand === undefined || isHelp(subcommand) ? 0 : 1;
 }
-async function runMediaFileUpload(args) {
+async function runMediaFileUpload(args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const allowedKeys = new Set([
         'hosted-operation-id',
@@ -391,12 +413,13 @@ async function runMediaFileUpload(args) {
             `postplus-cli:media-file:create-upload-url:${randomUUID()}`,
         quoteConfirmationToken: flags.values.get('quote-confirmation-token') ?? undefined,
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: async () => {
             const payload = await postHostedJson({
                 body,
                 pathName: '/api/postplus-cli/hosted/capability',
                 skillName: flags.values.get('skill') ?? null,
+                context,
             });
             const output = readHostedUploadOutput(payload);
             const signedUpload = readSignedUpload(output);
@@ -418,12 +441,13 @@ async function runMediaFileUpload(args) {
                 },
                 pathName: '/api/postplus-cli/hosted/capability',
                 skillName: flags.values.get('skill') ?? null,
+                context,
             });
         },
         errorInputLabel: inputFile,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 function readHostedUploadOutput(payload) {
     if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
@@ -503,16 +527,17 @@ function submitMediaGenerationRequest(params) {
         operationId: params.operationId,
         quoteConfirmationToken: params.quoteConfirmationToken ?? undefined,
     };
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body,
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: params.skillName,
+            context: params.context,
         }),
         errorInputLabel: params.errorInputLabel,
         json: params.json,
         outputPath: params.outputPath,
-    });
+    }, params.context);
 }
 // Poll a pending media-generation run: `postplus media poll --handle <run-id>`.
 // A media `create`/`transcribe`/`analyze` submit returns an async run handle
@@ -524,11 +549,11 @@ function submitMediaGenerationRequest(params) {
 // The body carries only the status quadruple; submit-only fields (input,
 // requestDimensions, quoteConfirmationToken) are never sent. Mirrors the
 // `research collect --run-handle` polling branch.
-async function runMediaPoll(args) {
+async function runMediaPoll(args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const handle = requireFlag(flags, 'handle');
     const outputPath = flags.values.get('output') ?? null;
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'media-generation',
@@ -538,11 +563,12 @@ async function runMediaPoll(args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName: null,
+            context,
         }),
         errorInputLabel: 'media-poll-handle',
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 function buildMediaVerbInput(input) {
     const record = {};
@@ -606,23 +632,24 @@ function buildMediaVerbInput(input) {
 // schemaVersion envelope), and posts to /hosted/collection. The resolved entry
 // gives the default skillName (overridable by `--skill`); the actorId stays
 // internal and is never placed on the public body.
-async function runResearchCollect(args) {
+async function runResearchCollect(args, context) {
     const [first, ...rest] = args;
     // Polling path: `research collect --run-handle <h>`. No positional collectionKey.
     if (!first || first.startsWith('--')) {
         const flags = parseFlags(args, new Set(['json']));
         const runHandle = requireFlag(flags, 'run-handle');
         const outputPath = flags.values.get('output') ?? null;
-        return runHostedCommand({
+        return dispatchHostedCommand({
             request: () => postHostedJson({
                 body: { runHandle, runHandleType: 'hosted-collection' },
                 pathName: '/api/postplus-cli/hosted/collection',
                 skillName: null,
+                context,
             }),
             errorInputLabel: 'research-collect-run-handle',
             json: flags.booleans.has('json'),
             outputPath,
-        });
+        }, context);
     }
     const verb = 'collect';
     const collectionKey = first;
@@ -652,9 +679,8 @@ async function runResearchCollect(args) {
             throw new Error(`Unknown option for research ${verb}: --${key}.`);
         }
     }
-    const requestPath = requireFlag(flags, 'request');
     const outputPath = flags.values.get('output') ?? null;
-    const raw = await readJsonFile(requestPath);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`research ${verb} ${collectionKey} --request must be a JSON object of collection input.`);
     }
@@ -673,7 +699,7 @@ async function runResearchCollect(args) {
         }
         maxTotalChargeUsd = parsed;
     }
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 collectionKey,
@@ -685,11 +711,12 @@ async function runResearchCollect(args) {
             },
             pathName: '/api/postplus-cli/hosted/collection',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // Manifest-driven public-content-collection verb (request-json surface). Resolves
 // the positional `<sourceKey>` against the research verb index for verb `scrape`,
@@ -698,7 +725,7 @@ async function runResearchCollect(args) {
 // capability `public-content-collection` / operation `scrape`. The resolved entry
 // gives the default skillName (overridable by `--skill`); the datasetId stays
 // internal and is never placed on the public body.
-async function runResearchScrape(args) {
+async function runResearchScrape(args, context) {
     const [first, ...rest] = args;
     const verb = 'scrape';
     const targets = RESEARCH_VERB_TARGETS.get(verb);
@@ -706,16 +733,17 @@ async function runResearchScrape(args) {
         const flags = parseFlags(args, new Set(['json']));
         const runHandle = requireFlag(flags, 'run-handle');
         const outputPath = flags.values.get('output') ?? null;
-        return runHostedCommand({
+        return dispatchHostedCommand({
             request: () => postHostedJson({
                 body: { runHandle, runHandleType: 'public-content-collection' },
                 pathName: '/api/postplus-cli/hosted/collection',
                 skillName: null,
+                context,
             }),
             errorInputLabel: 'research-scrape-run-handle',
             json: flags.booleans.has('json'),
             outputPath,
-        });
+        }, context);
     }
     const sourceKey = first;
     const resolved = targets?.get(sourceKey);
@@ -743,9 +771,8 @@ async function runResearchScrape(args) {
             throw new Error(`Unknown option for research ${verb}: --${key}.`);
         }
     }
-    const requestPath = requireFlag(flags, 'request');
     const outputPath = flags.values.get('output') ?? null;
-    const raw = await readJsonFile(requestPath);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!Array.isArray(raw) || raw.length === 0) {
         throw new Error(`research ${verb} ${sourceKey} --request must be a non-empty JSON array of scrape input records.`);
     }
@@ -766,7 +793,7 @@ async function runResearchScrape(args) {
     }
     // The Web /hosted/capability scrape contract is a strict object: skillName is
     // carried as the compatibility header (postHostedJson), never on the public body.
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'public-content-collection',
@@ -779,11 +806,12 @@ async function runResearchScrape(args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
 // Manifest-driven publish operation (request-json surface). The OPERATION is the
 // subcommand and the target: `postplus publish <operation> --request <file>`. The
@@ -792,7 +820,7 @@ async function runResearchScrape(args) {
 // Side-effecting operations surface the Web quote-confirmation challenge; the
 // shared runHostedCommand handles the challenge -> retry-with-token path. There is
 // no requestDimensions/approval/execute — those were private-runtime concepts.
-async function runPublishOperation(operation, args) {
+async function runPublishOperation(operation, args, context) {
     const resolved = PUBLISH_VERB_OPERATIONS.get(operation);
     if (!resolved) {
         throw new Error(`Unknown publish operation ${operation}. Valid: ${[...PUBLISH_VERB_OPERATIONS.keys()].join(', ')}.`);
@@ -816,9 +844,8 @@ async function runPublishOperation(operation, args) {
             throw new Error(`Unknown option for publish ${operation}: --${key}.`);
         }
     }
-    const requestPath = requireFlag(flags, 'request');
     const outputPath = flags.values.get('output') ?? null;
-    const raw = await readJsonFile(requestPath);
+    const { body: raw, errorInputLabel } = await resolveRequestBody(context, flags);
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error(`publish ${operation} --request must be a JSON object of publishing input.`);
     }
@@ -827,7 +854,7 @@ async function runPublishOperation(operation, args) {
     const operationId = flags.values.get('hosted-operation-id') ??
         `postplus-cli:publish:social-publishing:request:${randomUUID()}`;
     const quoteConfirmationToken = flags.values.get('quote-confirmation-token');
-    return runHostedCommand({
+    return dispatchHostedCommand({
         request: () => postHostedJson({
             body: {
                 capability: 'social-publishing',
@@ -838,13 +865,14 @@ async function runPublishOperation(operation, args) {
             },
             pathName: '/api/postplus-cli/hosted/capability',
             skillName,
+            context,
         }),
-        errorInputLabel: requestPath,
+        errorInputLabel,
         json: flags.booleans.has('json'),
         outputPath,
-    });
+    }, context);
 }
-async function runHostedSchema(domain, args) {
+async function runHostedSchema(domain, args, context) {
     const flags = parseFlags(args, new Set(['json']));
     const allowedFlags = domain === 'media'
         ? new Set(['endpoint'])
@@ -856,24 +884,40 @@ async function runHostedSchema(domain, args) {
             throw new Error(`Unknown option for ${domain} schema: --${key}.`);
         }
     }
-    writeJson(buildHostedRequestSchemaReport({
+    const report = buildHostedRequestSchemaReport({
         collectionKey: flags.values.get('collection-key') ?? null,
         domain,
         endpointKey: flags.values.get('endpoint') ?? null,
-    }));
+    });
+    // In-process / context path: RETURN the structured catalog so the model
+    // receives it as the call result. The bin path (no context) keeps writeJson +
+    // return 0 for human CLI stdout output. Mirrors the spend-verb dispatch.
+    if (context) {
+        return report;
+    }
+    writeJson(report);
     return 0;
 }
 async function postHostedJson(input) {
-    const auth = await resolveFreshRemoteAuth();
-    const response = await sendAuthedCloudRequest({
-        auth,
-        body: input.body,
-        method: 'POST',
-        pathName: input.pathName,
-        retryOn401: () => resolveFreshRemoteAuth({ forceRefresh: true }),
-        skillName: input.skillName,
-        timeoutMs: 120000,
-    });
+    const response = input.context
+        ? await sendAuthedCloudRequest({
+            auth: input.context.auth,
+            body: input.body,
+            method: 'POST',
+            pathName: input.pathName,
+            skillName: input.skillName,
+            skillsReleaseId: input.context.skillsReleaseId ?? null,
+            timeoutMs: 120000,
+        })
+        : await sendAuthedCloudRequest({
+            auth: await resolveFreshRemoteAuth(),
+            body: input.body,
+            method: 'POST',
+            pathName: input.pathName,
+            retryOn401: () => resolveFreshRemoteAuth({ forceRefresh: true }),
+            skillName: input.skillName,
+            timeoutMs: 120000,
+        });
     const payload = await readJsonResponse(response);
     if (!response.ok) {
         const productError = readHostedProductError(payload);
@@ -889,7 +933,7 @@ async function postHostedJson(input) {
     }
     return payload;
 }
-// Single exit path for every hosted command: success writes the result and
+// Single exit path for the BIN hosted command: success writes the result and
 // returns 0; a quote challenge writes the challenge file and rethrows actionable
 // guidance; a structured product error writes the full error envelope to the
 // result JSON and surfaces code/layer/operationId on the terminal, exiting 1.
@@ -921,6 +965,20 @@ async function runHostedCommand(input) {
     await writeResult(payload, input.outputPath, input.json);
     return 0;
 }
+// Single exit path for both BIN and LIB hosted commands. Each dispatch function
+// builds the SAME `request` closure (resolve verb -> build envelope -> POST) and
+// hands it here. The bin path (no `context`) keeps stdout/file/exit-code behavior
+// via runHostedCommand. The lib path (with `context`) returns the parsed payload
+// and rethrows the structured HostedProductRequestError / quote-confirmation error
+// VERBATIM — no stdout, no file writes, no exit code — so the in-process caller
+// surfaces the structured JSON and fails honestly. Because the closure is shared,
+// the wire request (URL + body + headers) is byte-identical across both paths.
+async function dispatchHostedCommand(input, context) {
+    if (!context) {
+        return runHostedCommand(input);
+    }
+    return input.request();
+}
 async function writeQuoteConfirmationChallenge(error, input) {
     const challengePath = path.resolve(input.outputPath
         ? `${input.outputPath}.quote-confirmation.json`

package/build/hosted-lib.d.ts

@@ -0,0 +1,34 @@
+import type { AuthedCloudRequestAuth } from './authed-cloud-request.js';
+export type HostedLibDomain = 'media' | 'research' | 'publish' | 'media-file';
+export type RunHostedRequestInput = {
+    /** Which hosted verb family `args` belongs to (the first CLI token). */
+    domain: HostedLibDomain;
+    /**
+     * The CLI tokens AFTER the domain, exactly as the bin would receive them, e.g.
+     * `['create', 'video-seedance-2-text']` or `['collect', 'tiktok-research']`.
+     * Flags surfaces still pass their `--flag value` tokens here; request-json
+     * surfaces pass the body via `requestJson` instead of a `--request <file>`.
+     */
+    args: string[];
+    /**
+     * The request-json envelope for request-json surfaces, injected in place of a
+     * `--request <file>` read. Omit it for flags surfaces (media create/transcribe
+     * flag-driven) and for surfaces that need no body (polling/run-handle).
+     */
+    requestJson?: Record<string, unknown> | unknown[];
+    /** The account's fresh session auth, supplied by the trusted host runtime. */
+    auth: AuthedCloudRequestAuth;
+    /**
+     * The skills release id stamped into `x-postplus-skills-release-id`. Provided
+     * verbatim by the host (it is NOT read from disk on this path).
+     */
+    skillsReleaseId?: string;
+};
+/**
+ * Runs a hosted media / research / publish / media-file request in-process and
+ * returns the parsed hosted payload. Throws the structured
+ * HostedProductRequestError / quote-confirmation error VERBATIM on failure — no
+ * stdout, no file writes, no exit code. The wire request is identical to the bin
+ * path for the same input (proven by the parity test).
+ */
+export declare function runHostedRequest(input: RunHostedRequestInput): Promise<unknown>;

package/build/hosted-lib.js

@@ -0,0 +1,45 @@
+// In-process hosted-execution library entry. This is the trusted-runtime
+// counterpart to the `postplus` bin: a host process (e.g. eve-agent) that already
+// holds the account's fresh session auth can run the SAME hosted verb grammar
+// in-process — resolve verb -> build the typed envelope -> POST -> return the
+// parsed payload — WITHOUT spawning a CLI subprocess, reading disk config, or
+// writing any temp/output file.
+//
+// Why this exists (anti-drift): the bin path and this lib path share ONE
+// resolve+build+post core in hosted-domain-commands.ts. For the same
+// domain+args+input+auth they produce a byte-identical hosted HTTP request (URL +
+// JSON body + headers). The only divergence is the input source and the result
+// sink, both injected via HostedRequestContext: auth + skillsReleaseId come in as
+// parameters (no `resolveFreshRemoteAuth()` disk read, no 401-refresh-retry — the
+// host supplies fresh session auth each turn), the request-json body comes from
+// `requestJson` instead of a `--request <file>`, and the parsed payload is RETURNED
+// (the structured HostedProductRequestError / quote-confirmation error are thrown
+// verbatim) instead of being written to stdout/file with an exit code.
+//
+// Scope: only the hosted spend/write surfaces go through here —
+// media / research / publish / media-file. Read-only diagnostics (status / doctor
+// / skills / whoami / quote / list / --version / --help) are NOT hosted-domain
+// commands and are out of scope for this entry.
+import { runHostedDomainCommand, runMediaFileCommand, } from './hosted-domain-commands.js';
+/**
+ * Runs a hosted media / research / publish / media-file request in-process and
+ * returns the parsed hosted payload. Throws the structured
+ * HostedProductRequestError / quote-confirmation error VERBATIM on failure — no
+ * stdout, no file writes, no exit code. The wire request is identical to the bin
+ * path for the same input (proven by the parity test).
+ */
+export async function runHostedRequest(input) {
+    const context = {
+        auth: input.auth,
+        ...(input.skillsReleaseId !== undefined
+            ? { skillsReleaseId: input.skillsReleaseId }
+            : {}),
+        ...(input.requestJson !== undefined
+            ? { requestJson: input.requestJson }
+            : {}),
+    };
+    if (input.domain === 'media-file') {
+        return runMediaFileCommand(input.args, context);
+    }
+    return runHostedDomainCommand(input.domain, input.args, context);
+}

package/build/hosted-manifest-index.d.ts

@@ -0,0 +1,69 @@
+export type HostedDomain = 'media' | 'publish' | 'research';
+export type ManifestFieldClass = 'intent' | 'default' | 'runner-managed';
+export type ManifestField = {
+    name: string;
+    class: ManifestFieldClass;
+    flag: string | null;
+    type: 'string' | 'number' | 'boolean' | 'media-url';
+    repeatable?: boolean;
+    enumValues?: readonly string[];
+    min?: number;
+    max?: number;
+    canonicalize?: 'lowercase' | 'image-resolution-tier';
+    default?: string | number | boolean;
+    required: boolean;
+    derivedFrom?: string;
+};
+export type ManifestEndpoint = {
+    endpointKey: string;
+    provider: string;
+    providerModelPath: string;
+    fields: readonly ManifestField[];
+    billingDimensions?: readonly string[];
+};
+export type ManifestModel = {
+    modelKey: string;
+    providerModelPath: string;
+};
+export type ManifestCollection = {
+    collectionKey: string;
+    actorId: string;
+};
+export type ManifestSource = {
+    sourceKey: string;
+    datasetId: string;
+};
+export type ManifestOperation = {
+    operation: string;
+};
+export type ManifestEntry = {
+    skill: string;
+    mode?: 'cli-runner';
+    surface: 'flags' | 'request-json';
+    verb: string;
+    domain: HostedDomain;
+    capability: string;
+    endpointKeys?: readonly string[];
+    modelKeys?: readonly string[];
+    collectionKeys?: readonly string[];
+    sourceKeys?: readonly string[];
+    endpoints?: readonly ManifestEndpoint[];
+    models?: readonly ManifestModel[];
+    collections?: readonly ManifestCollection[];
+    sources?: readonly ManifestSource[];
+    operations?: readonly ManifestOperation[];
+};
+export type ResolvedVerbTarget = {
+    skill: string;
+    capability: string;
+    surface: 'flags' | 'request-json';
+    endpoint?: ManifestEndpoint;
+    model?: ManifestModel;
+    collection?: ManifestCollection;
+    source?: ManifestSource;
+    operation?: string;
+};
+export declare function allManifestEntries(): ManifestEntry[];
+export declare function buildVerbTargetIndex(domain: HostedDomain): Map<string, Map<string, ResolvedVerbTarget>>;
+export declare function manifestTargetKeys(domain: HostedDomain, capability?: string): string[];
+export declare function findMediaEndpoint(endpointKey: string): ManifestEndpoint | null;

package/build/index.js

@@ -412,17 +412,19 @@ async function main() {
         case 'doctor':
             process.exitCode = await runDoctor(parseDiagnosticOptions(rest));
             return;
+        // The bin path never passes the in-process context, so these always resolve
+        // to the numeric exit code (the `unknown` return is the hosted-lib path only).
         case 'research':
-            process.exitCode = await runHostedDomainCommand('research', rest);
+            process.exitCode = (await runHostedDomainCommand('research', rest));
             return;
         case 'media':
-            process.exitCode = await runHostedDomainCommand('media', rest);
+            process.exitCode = (await runHostedDomainCommand('media', rest));
             return;
         case 'media-file':
-            process.exitCode = await runMediaFileCommand(rest);
+            process.exitCode = (await runMediaFileCommand(rest));
             return;
         case 'publish':
-            process.exitCode = await runHostedDomainCommand('publish', rest);
+            process.exitCode = (await runHostedDomainCommand('publish', rest));
             return;
         case 'quote':
             process.exitCode = await runQuoteCommand(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postplus/cli",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "packageManager": "pnpm@10.30.3+sha512.c961d1e0a2d8e354ecaa5166b822516668b7f44cb5bd95122d590dd81922f606f5473b6d23ec4a5be05e7fcd18e8488d47d978bbe981872f1145d06e9a740017",
   "type": "module",
   "description": "PostPlus CLI for PostPlus Cloud auth, status, and diagnostics.",
@@ -13,14 +13,19 @@
     "build/auth-validate.js",
     "build/auth.js",
     "build/authed-cloud-request.js",
+    "build/authed-cloud-request.d.ts",
     "build/client-compatibility.js",
     "build/command-runner.js",
     "build/doctor.js",
     "build/hosted-domain-commands.js",
+    "build/hosted-domain-commands.d.ts",
+    "build/hosted-lib.js",
+    "build/hosted-lib.d.ts",
     "build/generated/hosted-execution-manifest.generated.js",
     "build/generated/hosted-field-validation-core.generated.js",
     "build/hosted-field-validation.js",
     "build/hosted-manifest-index.js",
+    "build/hosted-manifest-index.d.ts",
     "build/hosted-release.js",
     "build/hosted-request-schemas.js",
     "build/index.js",
@@ -48,6 +53,13 @@
   "bin": {
     "postplus": "build/index.js"
   },
+  "exports": {
+    "./hosted-lib": {
+      "types": "./build/hosted-lib.d.ts",
+      "default": "./build/hosted-lib.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "node ./scripts/clean-build.mjs && tsc && node ./scripts/finalize-build.mjs",
     "clean": "rm -rf .turbo node_modules build",