getagenthook 0.2.1 → 1.0.1

package/README.md

@@ -1,5 +1,7 @@
 # agenthook
 
+[![npm](https://img.shields.io/npm/v/getagenthook?color=c6fe1e&label=getagenthook&style=flat-square)](https://www.npmjs.com/package/getagenthook)
+
 CLI for the AgentHook hosted media-generation API. Built for agents:
 progress goes to stderr, output URLs go to stdout, exit codes are meaningful.
 
@@ -10,7 +12,7 @@ agenthook login --key <your-api-key>
 agenthook tools
 agenthook run make_video --prompt "A barista holds a latte and says: try our new oat flat white" --quality pro --aspect-ratio 9:16 --captions
 agenthook run make_image --prompt "studio shot of a ceramic mug" --count 2
-agenthook run caption_video --video-url https://…/video.mp4 --style tiktok
+agenthook run caption_video --video-url https://…/video.mp4 --style chunk
 agenthook list --search "flat white"
 agenthook balance
 agenthook history
@@ -18,7 +20,7 @@ agenthook history
 
 - Credentials live at `~/.agenthook/credentials.json` (chmod 600).
 - API base: `--api-url` flag > `AGENTHOOK_API_URL` env > stored value >
-  `https://localhost:3000`; all requests hit `<base>/api/v1/…`.
+  `https://getagenthook.com`; all requests hit `<base>/api/v1/…`.
 - Reference images (`--ref`, repeatable) require `--owns-references`: you attest
   you own, or have the rights to use, the likeness of every person appearing in
   the referenced images.
@@ -27,4 +29,28 @@ agenthook history
   submitted: consent, prompt length caps, enum values, ranges, and
   `nano-banana-2` (edit-only) without references.
 
-Develop: `npm run build` (emits `dist/`), `npx vitest run`, `npx tsc --noEmit`.
+## MCP server
+
+If your agent speaks MCP, it can call AgentHook directly instead of going through
+the CLI. The server ships as `@getagenthook/mcp` and runs over `npx`. Add this to
+your MCP client config (Claude Code, Cursor, and similar):
+
+```json
+{
+  "mcpServers": {
+    "agenthook": {
+      "command": "npx",
+      "args": ["-y", "@getagenthook/mcp"],
+      "env": { "AGENTHOOK_API_KEY": "ah_your_key" }
+    }
+  }
+}
+```
+
+It exposes `make_video`, `make_image`, `caption_video`, and `create_influencer`,
+plus `get_run`. The generation tools return a `run_id`; pass it to `get_run` to
+fetch the finished URL once the job is done.
+
+## Develop
+
+`npm run build` (emits `dist/`), `npx vitest run`, `npx tsc --noEmit`.

package/dist/cli.js

@@ -33,8 +33,10 @@ Commands:
 Run flags:
   --prompt <text>  --ref <url> (repeatable)  --owns-references  --model <m>
   --quality <standard|pro>  --duration <s>  --aspect-ratio <r>  --no-audio
-  --captions  --caption-style <movie|tiktok>  --enhance-prompt
-  --video-url <url>  --style <movie|tiktok>  --count <n>  --resolution <1k|2k|4k>
+  --captions  --caption-style <chunk|highlight|subtitle>  --caption-size <small|medium|large>
+  --caption-placement <top|center|bottom>  --enhance-prompt
+  --video-url <url>  --style <chunk|highlight|subtitle>  --size <small|medium|large>
+  --placement <top|center|bottom>  --count <n>  --resolution <1k|2k|4k>
   --dry-run        price + validate against the server without spending credits
 
 Auth: pass --key, set AGENTHOOK_API_KEY, or run auth:login (precedence: flag > env > file).

package/dist/commands/run.js

@@ -38,36 +38,12 @@ const crypto = __importStar(require("node:crypto"));
 const args_1 = require("../args");
 const config_1 = require("../config");
 const exit_1 = require("../exit");
+const flags_1 = require("../flags");
 const http_1 = require("../http");
 const jobs_1 = require("../jobs");
 const schemas_1 = require("../schemas");
 const types_1 = require("../types");
 const validate_1 = require("../validate");
-const RUN_FLAGS = {
-    "api-url": "string",
-    key: "string",
-    json: "boolean",
-    "dry-run": "boolean",
-    prompt: "string",
-    ref: "array",
-    "owns-references": "boolean",
-    model: "string",
-    quality: "string",
-    duration: "number",
-    "aspect-ratio": "string",
-    "no-audio": "boolean",
-    captions: "boolean",
-    "caption-style": "string",
-    "enhance-prompt": "boolean",
-    "video-url": "string",
-    style: "string",
-    count: "number",
-    resolution: "string",
-    language: "string",
-    name: "string",
-    slug: "string",
-    influencer: "string",
-};
 // Poll cadence: 5s (spec); overridable for tests. Every watcher gets a
 // give-up (donor rule): a wall-clock deadline + bounded consecutive misses.
 const pollIntervalMs = () => Number(process.env.AGENTHOOK_POLL_MS || 5000);
@@ -77,7 +53,14 @@ const MAX_POLL_MISSES = 5;
 // submit must never double-charge; the server dedupes on the key).
 const SUBMIT_RETRIES = 1;
 async function run(argv) {
-    const { positionals, flags, errors } = (0, args_1.parseArgs)(argv, RUN_FLAGS);
+    // Flags are DERIVED from the live tool schema (so a new API param is a usable
+    // flag without a CLI upgrade), and the schema source is per-api-url — so the
+    // api-url is pulled from argv BEFORE the full parse, the schema is resolved,
+    // then the flag spec is built to parse against.
+    const apiUrl = (0, config_1.resolveApiUrl)(preScanApiUrl(argv));
+    const schemas = await (0, schemas_1.resolveRunSchemas)(apiUrl);
+    const { spec, paramForFlag, flagFor } = (0, flags_1.deriveRunFlags)(schemas);
+    const { positionals, flags, errors } = (0, args_1.parseArgs)(argv, spec);
     if (errors.length) {
         errors.forEach((e) => console.error(e));
         return exit_1.EXIT.GENERIC;
@@ -88,19 +71,16 @@ async function run(argv) {
         console.error("Usage: agenthook run <tool> [flags] — see `agenthook tools`");
         return exit_1.EXIT.GENERIC;
     }
-    const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
     const key = (0, config_1.resolveApiKey)(flags["key"]);
     if (!key) {
         emitError(asJson, "Not logged in — run `agenthook auth:login` first.", exit_1.EXIT.AUTH);
         return exit_1.EXIT.AUTH;
     }
-    // Deterministic pre-validation BEFORE any network call (spec §3) — schemas
-    // resolve locally in every case: cached /v1/tools fetch if one exists,
-    // otherwise the bundled snapshot (fresh install, offline). The server
-    // re-validates authoritatively on submit.
-    const schemas = (0, schemas_1.getLocalToolSchemas)(apiUrl);
-    const input = (0, validate_1.buildToolInput)(flags);
-    const problems = (0, validate_1.preValidate)(tool, input, schemas);
+    // Deterministic pre-validation BEFORE the run is submitted (spec §3): every
+    // locally-checkable rule the server would 400 on. The server re-validates
+    // authoritatively on submit.
+    const input = (0, validate_1.buildToolInput)(flags, paramForFlag);
+    const problems = (0, validate_1.preValidate)(tool, input, schemas, flagFor);
     if (problems.length) {
         if (asJson)
             emitError(true, problems.join("; "), exit_1.EXIT.VALIDATION);
@@ -231,6 +211,19 @@ async function submitWithRetry(apiUrl, tool, input, key, idempotencyKey) {
         }
     }
 }
+/** Pull --api-url out of raw argv before the flag spec exists (spec derivation
+ * needs the schema, fetched per api-url). Mirrors parseArgs' two forms; full
+ * precedence (flag > env > file > default) is applied by resolveApiUrl. */
+function preScanApiUrl(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--api-url")
+            return argv[i + 1];
+        if (a.startsWith("--api-url="))
+            return a.slice("--api-url=".length);
+    }
+    return undefined;
+}
 const topUpUrl = (apiUrl) => `${apiUrl}/credits`;
 /** Machine JSON to stdout (one object per line, ndjson). */
 function emit(obj) {

package/dist/commands/tools.js

@@ -4,9 +4,9 @@ exports.tools = tools;
 const args_1 = require("../args");
 const config_1 = require("../config");
 const exit_1 = require("../exit");
+const flags_1 = require("../flags");
 const json_error_1 = require("../json-error");
 const schemas_1 = require("../schemas");
-const validate_1 = require("../validate");
 async function tools(argv) {
     const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string", key: "string", json: "boolean" });
     if (errors.length) {
@@ -22,10 +22,13 @@ async function tools(argv) {
             console.log(JSON.stringify({ tools: schemas }));
             return exit_1.EXIT.OK;
         }
+        // Same derivation `run` parses against — the flag spelling shown here is
+        // exactly the one that will work.
+        const { flagFor } = (0, flags_1.deriveRunFlags)(schemas);
         for (const tool of schemas) {
             console.log(`${tool.name} — ${tool.description}`);
             for (const [name, spec] of Object.entries(tool.params)) {
-                console.log(`  ${renderParam(name, spec)}`);
+                console.log(`  ${renderParam(name, spec, flagFor)}`);
             }
             console.log("");
         }
@@ -33,8 +36,8 @@ async function tools(argv) {
         return exit_1.EXIT.OK;
     });
 }
-function renderParam(name, spec) {
-    const flagName = validate_1.FLAG_FOR[name] ?? `--${name.replace(/_/g, "-")}`;
+function renderParam(name, spec, flagFor) {
+    const flagName = flagFor[name] ?? `--${name.replace(/_/g, "-")}`;
     const hint = spec.type === "boolean"
         ? ""
         : spec.enum

package/dist/flags.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLAG_ALIAS = exports.CLI_FLAGS = void 0;
+exports.deriveRunFlags = deriveRunFlags;
+/** Flags that are NOT tool params and must always parse (any command shape). */
+exports.CLI_FLAGS = {
+    "api-url": "string",
+    key: "string",
+    json: "boolean",
+    "dry-run": "boolean",
+};
+/** The two places the CLI flag intentionally differs from a mechanical
+ * snake→kebab of the param name (everything else is derived). */
+exports.FLAG_ALIAS = {
+    reference_images: { flag: "ref" },
+    audio: { flag: "no-audio", invertBoolean: true }, // --no-audio sets audio:false
+};
+const FLAG_TYPES = ["string", "number", "boolean", "array"];
+/** Union every tool's params into the run flag spec + flag⇄param maps. Params
+ * repeat across tools (same flag name each time) — the union is idempotent. */
+function deriveRunFlags(schemas) {
+    const spec = { ...exports.CLI_FLAGS };
+    const paramForFlag = {};
+    const flagFor = {};
+    for (const schema of schemas) {
+        for (const [param, p] of Object.entries(schema.params)) {
+            const alias = exports.FLAG_ALIAS[param];
+            const flag = alias?.flag ?? param.replace(/_/g, "-");
+            let type = FLAG_TYPES.includes(p.type) ? p.type : "string";
+            if (alias?.invertBoolean)
+                type = "boolean";
+            spec[flag] = type;
+            paramForFlag[flag] = { param, invert: alias?.invertBoolean };
+            flagFor[param] = "--" + flag;
+        }
+    }
+    return { spec, paramForFlag, flagFor };
+}

package/dist/http.js

@@ -5,6 +5,7 @@ exports.timeoutSignal = timeoutSignal;
 exports.api = api;
 exports.describeApiError = describeApiError;
 const config_1 = require("./config");
+const version_1 = require("./version");
 // Timeout policy mirrors the frozen packages/core/net.ts (DEFAULT_TIMEOUT_MS +
 // AbortSignal.timeout). Duplicated here because the published CLI cannot
 // runtime-import workspace TypeScript; test/parity.test.ts pins the value.
@@ -36,7 +37,7 @@ async function api(apiUrl, pathname, opts = {}) {
         if (v !== undefined && v !== "")
             url.searchParams.set(k, v);
     }
-    const headers = { ...opts.headers };
+    const headers = { "user-agent": `agenthook-cli/${version_1.VERSION}`, ...opts.headers };
     if (opts.key)
         headers.authorization = `Bearer ${opts.key}`;
     if (opts.body !== undefined)

package/dist/schema-snapshot.js

@@ -26,8 +26,23 @@ exports.TOOLS_SNAPSHOT = [
                 default: "9:16",
             },
             audio: { type: "boolean", default: true },
-            captions: { type: "boolean", default: false },
-            caption_style: { type: "string", enum: ["movie", "tiktok"], default: "tiktok" },
+            captions: {
+                type: "boolean",
+                default: false,
+                description: "Burn spoken-word captions into the video. When true the run returns two files: output[0] is captioned, output[1] is the original uncaptioned video.",
+            },
+            caption_style: {
+                type: "string",
+                enum: ["chunk", "highlight", "subtitle"],
+                default: "chunk",
+                description: "Caption look. chunk = 2–4 words per line, centered, bold with a heavy outline (the standard TikTok/Reels style). highlight = the same block with the active word lit in colour (the Hormozi/retention style). subtitle = one clean line at the bottom (cinematic / YouTube).",
+            },
+            caption_size: { type: "string", enum: ["small", "medium", "large"], default: "medium", description: "Caption text size." },
+            caption_placement: {
+                type: "string",
+                enum: ["top", "center", "bottom"],
+                description: "Where captions sit. Defaults per style: chunk/highlight → center, subtitle → bottom.",
+            },
             enhance_prompt: { type: "boolean", default: false },
             influencer: {
                 type: "string",
@@ -62,10 +77,21 @@ exports.TOOLS_SNAPSHOT = [
     },
     {
         name: "caption_video",
-        description: "Burn styled subtitles into an existing video.",
+        description: "Burn styled captions into an existing video. Returns two files: output[0] is the captioned video, output[1] is the original uncaptioned video — so you can re-caption with a different style without regenerating. (A speechless video returns just the original.)",
         params: {
             video_url: { type: "string", required: true },
-            style: { type: "string", enum: ["movie", "tiktok"], default: "movie" },
+            style: {
+                type: "string",
+                enum: ["chunk", "highlight", "subtitle"],
+                default: "chunk",
+                description: "Caption look. chunk = bold centered word blocks (standard TikTok/Reels). highlight = active word lit in colour (Hormozi/retention). subtitle = clean bottom line (cinematic / YouTube).",
+            },
+            size: { type: "string", enum: ["small", "medium", "large"], default: "medium", description: "Caption text size." },
+            placement: {
+                type: "string",
+                enum: ["top", "center", "bottom"],
+                description: "Where captions sit. Defaults per style: chunk/highlight → center, subtitle → bottom.",
+            },
             language: { type: "string", default: "auto" },
         },
     },

package/dist/schemas.js

@@ -36,12 +36,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TOOLS_CACHE_TTL_MS = void 0;
 exports.toolsCachePath = toolsCachePath;
 exports.getLocalToolSchemas = getLocalToolSchemas;
+exports.resolveRunSchemas = resolveRunSchemas;
 exports.getToolSchemas = getToolSchemas;
-// Tool-schema source for deterministic pre-validation: GET /v1/tools is the
-// single live schema source (the `tools` command fetches + caches it), and
-// `run` validates against a purely LOCAL resolution — fetched cache if
-// present, else the bundled snapshot — so pre-validation never makes a
-// network call, including on a fresh install (spec §3).
+// Tool-schema source. GET /v1/tools is the single live schema source, and
+// `run` DERIVES its flags from it (a new API param is a usable flag with no CLI
+// upgrade) via resolveRunSchemas: the cached fetch when fresh, a live keyless
+// fetch on miss (public endpoint), and the bundled snapshot as the offline
+// fallback — so it stays current online and still works offline. (This relaxes
+// the original spec §3 "no network before submit" guarantee to a cached,
+// at-most-hourly, keyless fetch — the cost of never-stale flags.)
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const config_1 = require("./config");
@@ -72,6 +75,19 @@ function writeCache(cache) {
 function getLocalToolSchemas(apiUrl) {
     return readCache()[apiUrl]?.tools ?? schema_snapshot_1.TOOLS_SNAPSHOT;
 }
+/** Schema source for `run`'s flag derivation + pre-validation. Live-and-cached
+ * (GET /v1/tools is PUBLIC — no key) so a new tool param becomes a usable flag
+ * without a CLI upgrade; falls back to the last cache, then the bundled
+ * snapshot, so it never throws (offline / fresh install still work). The server
+ * re-validates authoritatively on submit. */
+async function resolveRunSchemas(apiUrl) {
+    try {
+        return await getToolSchemas(apiUrl);
+    }
+    catch {
+        return getLocalToolSchemas(apiUrl);
+    }
+}
 /** Cached-first schema load. `fresh: true` (the `tools` command) always
  * refetches; otherwise a fresh cache entry short-circuits the network, and a
  * stale one is the fallback when the API is unreachable (the server re-checks

package/dist/validate.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FLAG_FOR = exports.OWNS_REFERENCES_CONSENT = exports.PROMPT_CAPS = void 0;
+exports.OWNS_REFERENCES_CONSENT = exports.PROMPT_CAPS = void 0;
 exports.buildToolInput = buildToolInput;
 exports.preValidate = preValidate;
 // Per-model prompt caps, mirroring packages/core/models.ts promptMax (frozen).
@@ -13,69 +13,25 @@ exports.PROMPT_CAPS = {
 };
 exports.OWNS_REFERENCES_CONSENT = "By passing --owns-references you attest that you own, or have the rights to use, " +
     "the likeness of every person appearing in the referenced images.";
-/** CLI flag spelling for each API param — for readable error messages.
- * test/parity.test.ts asserts every param served by /v1/tools has an entry. */
-exports.FLAG_FOR = {
-    prompt: "--prompt",
-    reference_images: "--ref",
-    owns_references: "--owns-references",
-    model: "--model",
-    quality: "--quality",
-    duration: "--duration",
-    aspect_ratio: "--aspect-ratio",
-    audio: "--no-audio",
-    captions: "--captions",
-    caption_style: "--caption-style",
-    enhance_prompt: "--enhance-prompt",
-    video_url: "--video-url",
-    style: "--style",
-    count: "--count",
-    resolution: "--resolution",
-    language: "--language",
-    name: "--name",
-    slug: "--slug",
-    influencer: "--influencer",
-};
-/** Map parsed CLI flags onto the tool-input body the API expects. Only flags
- * the user actually passed are included, so server defaults stay in charge. */
-function buildToolInput(flags) {
+/** Map parsed CLI flags onto the tool-input body the API expects, using the
+ * flag→param map derived from the tool schema (see flags.ts). Only flags the
+ * user actually passed are present in `flags`, so server defaults stay in
+ * charge; a global CLI flag (api-url/key/json/dry-run) has no param and is
+ * skipped. The one non-direct case is `--no-audio` inverting to audio:false. */
+function buildToolInput(flags, paramForFlag) {
     const input = {};
-    const direct = [
-        ["prompt", "prompt"],
-        ["model", "model"],
-        ["quality", "quality"],
-        ["duration", "duration"],
-        ["aspect-ratio", "aspect_ratio"],
-        ["caption-style", "caption_style"],
-        ["video-url", "video_url"],
-        ["style", "style"],
-        ["count", "count"],
-        ["resolution", "resolution"],
-        ["language", "language"],
-        ["name", "name"],
-        ["slug", "slug"],
-        ["influencer", "influencer"],
-    ];
-    for (const [flag, param] of direct) {
-        if (flags[flag] !== undefined)
-            input[param] = flags[flag];
+    for (const [flag, value] of Object.entries(flags)) {
+        const mapping = paramForFlag[flag];
+        if (!mapping)
+            continue; // a global CLI flag, not a tool param
+        input[mapping.param] = mapping.invert ? !value : value;
     }
-    const refs = flags["ref"];
-    if (refs?.length)
-        input.reference_images = refs;
-    if (flags["owns-references"])
-        input.owns_references = true;
-    if (flags["no-audio"])
-        input.audio = false;
-    if (flags["captions"])
-        input.captions = true;
-    if (flags["enhance-prompt"])
-        input.enhance_prompt = true;
     return input;
 }
-const flag = (param) => exports.FLAG_FOR[param] ?? param;
-/** Returns human-readable problems (empty array = locally valid). */
-function preValidate(tool, input, schemas) {
+/** Returns human-readable problems (empty array = locally valid). `flagFor`
+ * (derived from the schema) supplies the CLI flag spelling for messages. */
+function preValidate(tool, input, schemas, flagFor) {
+    const flag = (param) => flagFor[param] ?? "--" + param.replace(/_/g, "-");
     const schema = schemas.find((s) => s.name === tool);
     if (!schema) {
         return [`Unknown tool "${tool}". Available tools: ${schemas.map((s) => s.name).join(", ")}`];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getagenthook",
-  "version": "0.2.1",
+  "version": "1.0.1",
   "description": "CLI for the AgentHook hosted media-generation API — generate video, images, and captions from your terminal or agent.",
   "license": "Apache-2.0",
   "homepage": "https://getagenthook.com",