getagenthook 0.1.0 → 0.2.1

package/dist/cli.js

@@ -1,48 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
+const auth_login_1 = require("./commands/auth-login");
 const balance_1 = require("./commands/balance");
 const history_1 = require("./commands/history");
+const influencers_1 = require("./commands/influencers");
+const jobs_1 = require("./commands/jobs");
 const list_1 = require("./commands/list");
 const login_1 = require("./commands/login");
 const run_1 = require("./commands/run");
 const tools_1 = require("./commands/tools");
+const exit_1 = require("./exit");
 const http_1 = require("./http");
+const version_1 = require("./version");
 const USAGE = `agenthook — hosted media generation for agents
 
 Usage: agenthook <command> [flags]
 
 Commands:
-  login [--key <key>]                     store your API key (chmod 600)
+  auth:login                              keyless device flow — approve in the console
+  login [--key <key>]                     keyless device flow, or store a pasted key
   tools                                   list tools + parameters (from GET /v1/tools)
   run <tool> [flags]                      submit a run, poll every 5s, print output URL(s)
   list [--tool t] [--status s] [--search q]   your past generations
+  influencers                             list your saved influencers (slug / name / portrait)
+  influencers:delete <slug>               delete a saved influencer
   balance                                 credit balance
   history                                 credit ledger
+  jobs                                    local run ledger (~/.agenthook/jobs.jsonl)
+  version                                 print the CLI version (also --version / -v)
 
 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>
+  --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).
+--json on run/list/balance/history/tools/jobs emits machine JSON on stdout, progress on stderr.
 Every command accepts --api-url <url> (or AGENTHOOK_API_URL; default https://getagenthook.com).`;
 async function runCli(argv) {
     const [cmd, ...rest] = argv;
     try {
         switch (cmd) {
+            case "auth:login":
+                return await (0, auth_login_1.authLogin)(rest);
             case "login":
-                return await (0, login_1.login)(rest);
+                // Keyless `login` falls through to the device flow; `login --key <k>`
+                // keeps the paste path (still supported for CI/pre-provisioned keys).
+                return rest.includes("--key") ? await (0, login_1.login)(rest) : await (0, auth_login_1.authLogin)(rest);
             case "tools":
                 return await (0, tools_1.tools)(rest);
             case "run":
                 return await (0, run_1.run)(rest);
             case "list":
                 return await (0, list_1.list)(rest);
+            case "influencers":
+                return await (0, influencers_1.influencers)(rest);
+            case "influencers:delete":
+                return await (0, influencers_1.influencersDelete)(rest);
             case "balance":
                 return await (0, balance_1.balance)(rest);
             case "history":
                 return await (0, history_1.history)(rest);
+            case "jobs":
+                return await (0, jobs_1.jobs)(rest);
+            case "version":
+            case "--version":
+            case "-v":
+                // Agents probe this to detect a stale install — must exit 0 with the
+                // package version, never fall through to "Unknown command" (exit 1).
+                console.log(version_1.VERSION);
+                return 0;
             case undefined:
             case "help":
             case "--help":
@@ -57,7 +87,7 @@ async function runCli(argv) {
     catch (e) {
         if (e instanceof http_1.ApiError) {
             console.error((0, http_1.describeApiError)(e));
-            return 1;
+            return (0, exit_1.exitCodeForApiError)(e);
         }
         console.error(e instanceof Error ? e.message : String(e));
         return 1;

package/dist/commands/auth-login.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authLogin = authLogin;
+const os = __importStar(require("node:os"));
+const args_1 = require("../args");
+const config_1 = require("../config");
+const exit_1 = require("../exit");
+const http_1 = require("../http");
+// Poll cadence: 5s (spec); AGENTHOOK_POLL_MS override mirrors run.ts:30.
+const pollIntervalMs = () => Number(process.env.AGENTHOOK_POLL_MS || 5000);
+// Keyless device flow: create a session, print the approved shape verbatim,
+// poll until a human approves in the console, then save the minted key.
+// `requesting_host = os.hostname()` so the approve screen can name the agent.
+async function authLogin(argv) {
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string" });
+    if (errors.length) {
+        errors.forEach((e) => console.error(e));
+        return exit_1.EXIT.GENERIC;
+    }
+    const apiUrlFlag = flags["api-url"];
+    const apiUrl = (0, config_1.resolveApiUrl)(apiUrlFlag);
+    let session;
+    try {
+        session = await (0, http_1.api)(apiUrl, "/device", {
+            method: "POST",
+            body: { requesting_host: os.hostname() },
+        });
+    }
+    catch (e) {
+        if (e instanceof http_1.ApiError) {
+            console.error(`Could not start authorization against ${apiUrl}: ${e.message}`);
+            return e.status === 401 || e.status === 403 ? exit_1.EXIT.AUTH : exit_1.EXIT.GENERIC;
+        }
+        throw e;
+    }
+    // Approved output shape (verbatim — AC1). Human-facing, so it goes to stdout.
+    console.log("To authorize this agent, ask your human to visit:\n\n" +
+        `    ${session.device_url}\n` +
+        `    and enter code:  ${session.user_code}\n\n` +
+        "Waiting for approval… (expires in 15m)");
+    // Poll GET /device/:pollToken until terminal. A network blip is retried
+    // silently until the code expires server-side (poll returns `expired`).
+    for (;;) {
+        await sleep(pollIntervalMs());
+        let poll;
+        try {
+            poll = await (0, http_1.api)(apiUrl, `/device/${encodeURIComponent(session.poll_token)}`);
+        }
+        catch (e) {
+            if (e instanceof http_1.ApiError && e.status === 404) {
+                console.error("Device session not found — it may have expired. Run `agenthook auth:login` again.");
+                return exit_1.EXIT.AUTH;
+            }
+            continue; // transient — keep polling until the server reports terminal state
+        }
+        switch (poll.status) {
+            case "pending":
+                continue;
+            case "approved": {
+                const creds = {
+                    ...(0, config_1.loadCredentials)(),
+                    api_key: poll.api_key,
+                    ...(apiUrlFlag ? { api_url: apiUrl } : {}),
+                };
+                const p = (0, config_1.saveCredentials)(creds);
+                console.log(`✓ Authorized as ${poll.email}\n  Key saved to ${p}`);
+                return exit_1.EXIT.OK;
+            }
+            case "expired":
+                console.error("The authorization code expired before it was approved. Run `agenthook auth:login` again.");
+                return exit_1.EXIT.AUTH;
+            case "claimed":
+                console.error("This authorization code was already used. Run `agenthook auth:login` again.");
+                return exit_1.EXIT.AUTH;
+        }
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/commands/balance.js

@@ -3,22 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.balance = balance;
 const args_1 = require("../args");
 const config_1 = require("../config");
+const exit_1 = require("../exit");
 const http_1 = require("../http");
+const json_error_1 = require("../json-error");
 async function balance(argv) {
-    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string" });
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string", key: "string", json: "boolean" });
     if (errors.length) {
         errors.forEach((e) => console.error(e));
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
-    const key = (0, config_1.storedApiKey)();
+    const asJson = flags["json"] === true;
+    const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
     if (!key) {
-        console.error("Not logged in — run `agenthook login` first.");
-        return 1;
+        console.error("Not logged in — run `agenthook auth:login` first.");
+        return exit_1.EXIT.AUTH;
     }
-    const me = await (0, http_1.api)((0, config_1.resolveApiUrl)(flags["api-url"]), "/me", { key });
-    console.log(`User:    ${me.user_id}`);
-    console.log(`Balance: ${me.balance} credits`);
-    if (me.suspended)
-        console.error("Account suspended — new runs are refused.");
-    return 0;
+    return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+        const me = await (0, http_1.api)(apiUrl, "/me", { key });
+        if (asJson) {
+            console.log(JSON.stringify(me));
+        }
+        else {
+            console.log(`User:    ${me.user_id}`);
+            console.log(`Balance: ${me.balance} credits`);
+            if (me.suspended)
+                console.error("Account suspended — new runs are refused.");
+        }
+        return exit_1.EXIT.OK;
+    });
 }

package/dist/commands/history.js

@@ -3,33 +3,42 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.history = history;
 const args_1 = require("../args");
 const config_1 = require("../config");
+const exit_1 = require("../exit");
 const http_1 = require("../http");
+const json_error_1 = require("../json-error");
 const render_1 = require("../render");
 async function history(argv) {
-    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string" });
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string", key: "string", json: "boolean" });
     if (errors.length) {
         errors.forEach((e) => console.error(e));
-        return 1;
-    }
-    const key = (0, config_1.storedApiKey)();
-    if (!key) {
-        console.error("Not logged in — run `agenthook login` first.");
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
+    const asJson = flags["json"] === true;
     const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
-    const res = await (0, http_1.api)(apiUrl, "/credits/history", { key });
-    if (res.entries.length === 0) {
-        console.log("No credit activity yet.");
-    }
-    else {
-        const rows = res.entries.map((e) => [
-            e.created_at,
-            e.reason,
-            e.delta > 0 ? `+${e.delta}` : String(e.delta),
-            e.run_id ?? "-",
-        ]);
-        console.log((0, render_1.table)(["CREATED", "REASON", "DELTA", "RUN"], rows));
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
+    if (!key) {
+        console.error("Not logged in — run `agenthook auth:login` first.");
+        return exit_1.EXIT.AUTH;
     }
-    console.log(`Balance: ${res.balance} credits`);
-    return 0;
+    return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+        const res = await (0, http_1.api)(apiUrl, "/credits/history", { key });
+        if (asJson) {
+            console.log(JSON.stringify(res));
+            return exit_1.EXIT.OK;
+        }
+        if (res.entries.length === 0) {
+            console.log("No credit activity yet.");
+        }
+        else {
+            const rows = res.entries.map((e) => [
+                e.created_at,
+                e.reason,
+                e.delta > 0 ? `+${e.delta}` : String(e.delta),
+                e.run_id ?? "-",
+            ]);
+            console.log((0, render_1.table)(["CREATED", "REASON", "DELTA", "RUN"], rows));
+        }
+        console.log(`Balance: ${res.balance} credits`);
+        return exit_1.EXIT.OK;
+    });
 }

package/dist/commands/influencers.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.influencers = influencers;
+exports.influencersDelete = influencersDelete;
+const args_1 = require("../args");
+const config_1 = require("../config");
+const exit_1 = require("../exit");
+const http_1 = require("../http");
+const json_error_1 = require("../json-error");
+const render_1 = require("../render");
+const AUTH_FLAGS = { "api-url": "string", key: "string", json: "boolean" };
+/** `agenthook influencers` — GET /v1/influencers, the account's roster. */
+async function influencers(argv) {
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { ...AUTH_FLAGS });
+    if (errors.length) {
+        errors.forEach((e) => console.error(e));
+        return exit_1.EXIT.GENERIC;
+    }
+    const asJson = flags["json"] === true;
+    const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
+    if (!key) {
+        console.error("Not logged in — run `agenthook auth:login` first.");
+        return exit_1.EXIT.AUTH;
+    }
+    return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+        const res = await (0, http_1.api)(apiUrl, "/influencers", { key });
+        if (asJson) {
+            console.log(JSON.stringify(res));
+            return exit_1.EXIT.OK;
+        }
+        if (res.influencers.length === 0) {
+            console.log("No influencers yet — create one with `agenthook run create_influencer`.");
+            return exit_1.EXIT.OK;
+        }
+        const rows = res.influencers.map((i) => [i.slug, i.name, i.portrait_url]);
+        console.log((0, render_1.table)(["SLUG", "NAME", "PORTRAIT"], rows));
+        return exit_1.EXIT.OK;
+    });
+}
+/** `agenthook influencers:delete <slug>` — DELETE /v1/influencers/:slug. */
+async function influencersDelete(argv) {
+    const { positionals, flags, errors } = (0, args_1.parseArgs)(argv, { ...AUTH_FLAGS });
+    if (errors.length) {
+        errors.forEach((e) => console.error(e));
+        return exit_1.EXIT.GENERIC;
+    }
+    const asJson = flags["json"] === true;
+    const slug = positionals[0];
+    if (!slug) {
+        console.error("Usage: agenthook influencers:delete <slug>");
+        return exit_1.EXIT.GENERIC;
+    }
+    const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
+    if (!key) {
+        console.error("Not logged in — run `agenthook auth:login` first.");
+        return exit_1.EXIT.AUTH;
+    }
+    try {
+        await (0, http_1.api)(apiUrl, `/influencers/${encodeURIComponent(slug)}`, {
+            method: "DELETE",
+            key,
+        });
+    }
+    catch (e) {
+        // A 404 gets a clear, slug-named message; every other ApiError maps through
+        // the frozen taxonomy (401/403 → AUTH exit 2) via guardJson's re-emission.
+        if (e instanceof http_1.ApiError && e.status === 404) {
+            if (asJson)
+                console.log(JSON.stringify({ error: `No influencer with slug "${slug}".`, exit_code: exit_1.EXIT.GENERIC }));
+            else
+                console.error(`No influencer with slug "${slug}".`);
+            return exit_1.EXIT.GENERIC;
+        }
+        return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+            throw e;
+        });
+    }
+    if (asJson)
+        console.log(JSON.stringify({ deleted: true }));
+    else
+        console.log(`Deleted ${slug}.`);
+    return exit_1.EXIT.OK;
+}

package/dist/commands/jobs.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jobs = jobs;
+const args_1 = require("../args");
+const exit_1 = require("../exit");
+const jobs_1 = require("../jobs");
+const render_1 = require("../render");
+// Reads the local jobs ledger (<config-dir>/jobs.jsonl) — the CLI's own record
+// of every submit + terminal event. Offline, no network, no key needed.
+async function jobs(argv) {
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { json: "boolean" });
+    if (errors.length) {
+        errors.forEach((e) => console.error(e));
+        return exit_1.EXIT.GENERIC;
+    }
+    const entries = (0, jobs_1.readJobs)();
+    if (flags["json"] === true) {
+        for (const e of entries)
+            console.log(JSON.stringify(e));
+        return exit_1.EXIT.OK;
+    }
+    if (entries.length === 0) {
+        console.log("No jobs recorded yet.");
+        return exit_1.EXIT.OK;
+    }
+    const rows = entries.map((e) => [
+        e.ts,
+        e.run_id,
+        e.tool,
+        e.status,
+        (0, render_1.truncate)(e.output[0] ?? "", 48),
+    ]);
+    console.log((0, render_1.table)(["TS", "RUN", "TOOL", "STATUS", "OUTPUT"], rows));
+    return exit_1.EXIT.OK;
+}

package/dist/commands/list.js

@@ -3,47 +3,58 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.list = list;
 const args_1 = require("../args");
 const config_1 = require("../config");
+const exit_1 = require("../exit");
 const http_1 = require("../http");
+const json_error_1 = require("../json-error");
 const render_1 = require("../render");
 async function list(argv) {
     const { flags, errors } = (0, args_1.parseArgs)(argv, {
         "api-url": "string",
+        key: "string",
+        json: "boolean",
         tool: "string",
         status: "string",
         search: "string",
     });
     if (errors.length) {
         errors.forEach((e) => console.error(e));
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
+    const asJson = flags["json"] === true;
     const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
-    const key = (0, config_1.storedApiKey)();
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
     if (!key) {
-        console.error("Not logged in — run `agenthook login` first.");
-        return 1;
+        console.error("Not logged in — run `agenthook auth:login` first.");
+        return exit_1.EXIT.AUTH;
     }
-    const res = await (0, http_1.api)(apiUrl, "/generations", {
-        key,
-        query: {
-            tool: flags["tool"],
-            status: flags["status"],
-            q: flags["search"],
-        },
+    return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+        const res = await (0, http_1.api)(apiUrl, "/generations", {
+            key,
+            query: {
+                tool: flags["tool"],
+                status: flags["status"],
+                q: flags["search"],
+            },
+        });
+        if (asJson) {
+            console.log(JSON.stringify(res));
+            return exit_1.EXIT.OK;
+        }
+        if (res.runs.length === 0) {
+            console.log("No generations found.");
+            return exit_1.EXIT.OK;
+        }
+        const rows = res.runs.map((r) => [
+            r.id,
+            r.tool,
+            r.status,
+            r.created_at,
+            String(r.credits_charged),
+            r.output[0] ?? (r.error ? (0, render_1.truncate)(r.error, 40) : (0, render_1.truncate)(r.prompt ?? "", 40)),
+        ]);
+        console.log((0, render_1.table)(["ID", "TOOL", "STATUS", "CREATED", "CREDITS", "OUTPUT"], rows));
+        if (res.next_cursor)
+            console.error("(more results available — narrow with --tool/--status/--search)");
+        return exit_1.EXIT.OK;
     });
-    if (res.runs.length === 0) {
-        console.log("No generations found.");
-        return 0;
-    }
-    const rows = res.runs.map((r) => [
-        r.id,
-        r.tool,
-        r.status,
-        r.created_at,
-        String(r.credits_charged),
-        r.output[0] ?? (r.error ? (0, render_1.truncate)(r.error, 40) : (0, render_1.truncate)(r.prompt ?? "", 40)),
-    ]);
-    console.log((0, render_1.table)(["ID", "TOOL", "STATUS", "CREATED", "CREDITS", "OUTPUT"], rows));
-    if (res.next_cursor)
-        console.error("(more results available — narrow with --tool/--status/--search)");
-    return 0;
 }

package/dist/commands/run.js

@@ -1,13 +1,53 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = run;
+const crypto = __importStar(require("node:crypto"));
 const args_1 = require("../args");
 const config_1 = require("../config");
+const exit_1 = require("../exit");
 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",
@@ -24,28 +64,35 @@ const RUN_FLAGS = {
     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);
 const POLL_DEADLINE_MS = 60 * 60 * 1000; // the server sweep fails stuck runs at 45min; we outlast it
 const MAX_POLL_MISSES = 5;
+// One transient re-submit with the SAME idempotency key (spec AC7 — a retried
+// 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);
     if (errors.length) {
         errors.forEach((e) => console.error(e));
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
+    const asJson = flags["json"] === true;
     const tool = positionals[0];
     if (!tool) {
         console.error("Usage: agenthook run <tool> [flags] — see `agenthook tools`");
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
     const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
-    const key = (0, config_1.storedApiKey)();
+    const key = (0, config_1.resolveApiKey)(flags["key"]);
     if (!key) {
-        console.error("Not logged in — run `agenthook login` first.");
-        return 1;
+        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,
@@ -55,28 +102,66 @@ async function run(argv) {
     const input = (0, validate_1.buildToolInput)(flags);
     const problems = (0, validate_1.preValidate)(tool, input, schemas);
     if (problems.length) {
-        problems.forEach((p) => console.error(p));
-        return 1;
+        if (asJson)
+            emitError(true, problems.join("; "), exit_1.EXIT.VALIDATION);
+        else
+            problems.forEach((p) => console.error(p));
+        return exit_1.EXIT.VALIDATION;
+    }
+    // Free pre-flight: POST with `dry_run` so the server prices + validates
+    // authoritatively without creating a run or debiting. No idempotency key
+    // (nothing is charged) and no poll — the priced response is terminal.
+    if (flags["dry-run"] === true) {
+        let dry;
+        try {
+            dry = await (0, http_1.api)(apiUrl, `/tools/${encodeURIComponent(tool)}/run`, {
+                method: "POST",
+                key,
+                body: { ...input, dry_run: true },
+            });
+        }
+        catch (e) {
+            if (e instanceof http_1.ApiError) {
+                const code = (0, exit_1.exitCodeForApiError)(e);
+                if (asJson)
+                    emitError(true, e.message, code, e.status === 402 ? topUpUrl(apiUrl) : undefined, e.details);
+                else
+                    console.error((0, http_1.describeApiError)(e));
+                return code;
+            }
+            throw e;
+        }
+        if (asJson)
+            emit(dry);
+        else
+            console.log(`Would cost ${dry.credits_required} credits${dry.model ? ` (model ${dry.model})` : ""}. No credits charged.`);
+        return exit_1.EXIT.OK;
     }
-    // Submit.
+    // Idempotency key generated once and reused across transient re-submits, so
+    // a network hiccup mid-submit can retry without a second debit (spec AC5/AC7).
+    const idempotencyKey = crypto.randomUUID();
     let created;
     try {
-        created = await (0, http_1.api)(apiUrl, `/tools/${encodeURIComponent(tool)}/run`, {
-            method: "POST",
-            key,
-            body: input,
-        });
+        created = await submitWithRetry(apiUrl, tool, input, key, idempotencyKey);
     }
     catch (e) {
         if (e instanceof http_1.ApiError) {
-            console.error((0, http_1.describeApiError)(e));
-            return 1;
+            const code = (0, exit_1.exitCodeForApiError)(e);
+            if (asJson)
+                emitError(true, e.message, code, e.status === 402 ? topUpUrl(apiUrl) : undefined, e.details);
+            else
+                console.error((0, http_1.describeApiError)(e));
+            return code;
         }
         throw e;
     }
+    // Submit ledger row + submit JSON object (first ndjson line).
+    (0, jobs_1.appendJob)({ ts: new Date().toISOString(), run_id: created.run_id, tool, status: "submit", output: [] });
+    if (asJson)
+        emit(created);
     console.error(`Run ${created.run_id} submitted (${created.credits_charged} credits). Polling…`);
-    // Poll until terminal. Progress goes to stderr; output URLs alone go to
-    // stdout so agents/scripts can capture them cleanly.
+    // Poll until terminal. In --json mode the terminal RunResponse is the second
+    // ndjson line on stdout; otherwise output URLs alone go to stdout.
     const deadline = Date.now() + POLL_DEADLINE_MS;
     let lastStatus = created.status;
     let misses = 0;
@@ -89,14 +174,14 @@ async function run(argv) {
         }
         catch (e) {
             if (e instanceof http_1.ApiError && e.status === 404) {
-                console.error(`Run ${created.run_id} no longer exists (404).`);
-                return 1;
+                emitError(asJson, `Run ${created.run_id} no longer exists (404).`, exit_1.EXIT.GENERIC);
+                return exit_1.EXIT.GENERIC;
             }
             misses++;
             if (misses >= MAX_POLL_MISSES) {
-                console.error(`Lost contact with the API (${MAX_POLL_MISSES} consecutive failures: ${e.message}).\n` +
-                    `The run may still finish — check later with: agenthook list`);
-                return 1;
+                emitError(asJson, `Lost contact with the API (${MAX_POLL_MISSES} consecutive failures: ${e.message}). ` +
+                    `The run may still finish — check later with: agenthook list`, exit_1.EXIT.GENERIC);
+                return exit_1.EXIT.GENERIC;
             }
             continue;
         }
@@ -105,17 +190,64 @@ async function run(argv) {
             lastStatus = runRow.status;
         }
         if (runRow.status === "completed") {
-            for (const url of runRow.output)
-                console.log(url);
-            return 0;
+            (0, jobs_1.appendJob)({ ts: new Date().toISOString(), run_id: runRow.id, tool, status: "completed", output: runRow.output });
+            if (asJson)
+                emit(runRow);
+            else
+                for (const url of runRow.output)
+                    console.log(url);
+            return exit_1.EXIT.OK;
         }
         if (runRow.status === "failed") {
-            console.error(`Run failed: ${runRow.error ?? "unknown error"} (credits are refunded automatically)`);
-            return 1;
+            (0, jobs_1.appendJob)({ ts: new Date().toISOString(), run_id: runRow.id, tool, status: "failed", output: [] });
+            if (asJson)
+                emit(runRow);
+            else
+                console.error(`Run failed: ${runRow.error ?? "unknown error"} (credits are refunded automatically)`);
+            return exit_1.EXIT.GENERIC;
         }
     }
-    console.error(`Run ${created.run_id} did not finish within ${POLL_DEADLINE_MS / 60_000} minutes — ` +
-        `giving up on polling. Check later with: agenthook list`);
-    return 1;
+    emitError(asJson, `Run ${created.run_id} did not finish within ${POLL_DEADLINE_MS / 60_000} minutes — ` +
+        `giving up on polling. Check later with: agenthook list`, exit_1.EXIT.GENERIC);
+    return exit_1.EXIT.GENERIC;
+}
+/** Submit, retrying transient network failures with the SAME idempotency key. */
+async function submitWithRetry(apiUrl, tool, input, key, idempotencyKey) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await (0, http_1.api)(apiUrl, `/tools/${encodeURIComponent(tool)}/run`, {
+                method: "POST",
+                key,
+                body: input,
+                headers: { [types_1.IDEMPOTENCY_KEY_HEADER]: idempotencyKey },
+            });
+        }
+        catch (e) {
+            // Only retry pure network/timeout failures (status 0); an HTTP error is
+            // deterministic and re-sending won't change it.
+            if (e instanceof http_1.ApiError && e.status === 0 && attempt < SUBMIT_RETRIES)
+                continue;
+            throw e;
+        }
+    }
+}
+const topUpUrl = (apiUrl) => `${apiUrl}/credits`;
+/** Machine JSON to stdout (one object per line, ndjson). */
+function emit(obj) {
+    console.log(JSON.stringify(obj));
+}
+/** Human message to stderr, or a JSON error object to stdout under --json.
+ * A server 400 carries a `details: [{path,message}]` array naming the offending
+ * params — surfaced in the JSON so an agent needn't re-run without --json. */
+function emitError(asJson, message, code, top_up_url, details) {
+    if (asJson)
+        console.log(JSON.stringify({
+            error: message,
+            exit_code: code,
+            ...(details && details.length ? { details } : {}),
+            ...(top_up_url ? { top_up_url } : {}),
+        }));
+    else
+        console.error(message);
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/commands/tools.js

@@ -3,26 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.tools = tools;
 const args_1 = require("../args");
 const config_1 = require("../config");
+const exit_1 = require("../exit");
+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" });
+    const { flags, errors } = (0, args_1.parseArgs)(argv, { "api-url": "string", key: "string", json: "boolean" });
     if (errors.length) {
         errors.forEach((e) => console.error(e));
-        return 1;
+        return exit_1.EXIT.GENERIC;
     }
+    const asJson = flags["json"] === true;
     const apiUrl = (0, config_1.resolveApiUrl)(flags["api-url"]);
-    // Always fetch fresh (and warm the cache `run` pre-validates from).
-    const schemas = await (0, schemas_1.getToolSchemas)(apiUrl, (0, config_1.storedApiKey)(), { fresh: true });
-    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)}`);
+    return (0, json_error_1.guardJson)(asJson, apiUrl, async () => {
+        // Always fetch fresh (and warm the cache `run` pre-validates from).
+        const schemas = await (0, schemas_1.getToolSchemas)(apiUrl, (0, config_1.resolveApiKey)(flags["key"]), { fresh: true });
+        if (asJson) {
+            console.log(JSON.stringify({ tools: schemas }));
+            return exit_1.EXIT.OK;
         }
-        console.log("");
-    }
-    console.log(`Run one with: agenthook run <tool> --prompt "..." [flags]`);
-    return 0;
+        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("");
+        }
+        console.log(`Run one with: agenthook run <tool> --prompt "..." [flags]`);
+        return exit_1.EXIT.OK;
+    });
 }
 function renderParam(name, spec) {
     const flagName = validate_1.FLAG_FOR[name] ?? `--${name.replace(/_/g, "-")}`;

package/dist/config.js

@@ -36,10 +36,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.BASE_PATH = void 0;
 exports.configDir = configDir;
 exports.credentialsPath = credentialsPath;
+exports.jobsPath = jobsPath;
 exports.loadCredentials = loadCredentials;
 exports.saveCredentials = saveCredentials;
 exports.resolveApiUrl = resolveApiUrl;
 exports.storedApiKey = storedApiKey;
+exports.resolveApiKey = resolveApiKey;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
@@ -52,6 +54,10 @@ function configDir() {
 function credentialsPath() {
     return path.join(configDir(), "credentials.json");
 }
+/** Local jobs ledger — one JSON line per run submit + terminal event. */
+function jobsPath() {
+    return path.join(configDir(), "jobs.jsonl");
+}
 function loadCredentials() {
     try {
         return JSON.parse(fs.readFileSync(credentialsPath(), "utf8"));
@@ -73,6 +79,11 @@ function resolveApiUrl(flagValue) {
     const url = flagValue || process.env.AGENTHOOK_API_URL || loadCredentials().api_url || exports.DEFAULT_API_URL;
     return url.replace(/\/+$/, "");
 }
+/** File-only key (used by `login` to display "already stored"; commands use resolveApiKey). */
 function storedApiKey() {
     return loadCredentials().api_key;
 }
+/** Resolution order: --key flag > AGENTHOOK_API_KEY env > credentials file. */
+function resolveApiKey(flagValue) {
+    return flagValue || process.env.AGENTHOOK_API_KEY || loadCredentials().api_key;
+}

package/dist/exit.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT = void 0;
+exports.exitCodeForApiError = exitCodeForApiError;
+exports.EXIT = {
+    OK: 0,
+    GENERIC: 1, // any uncategorized failure (network, bad args, run failed)
+    AUTH: 2, // 401/403, and a device session that expired/was already claimed
+    VALIDATION: 3, // 400 — malformed request the server rejected
+    INSUFFICIENT_CREDITS: 4, // 402 — out of credits (carries top_up_url in --json)
+};
+/** Maps an ApiError's HTTP status onto the frozen taxonomy. Status 0
+ * (network/timeout) and everything unmapped fall through to GENERIC. */
+function exitCodeForApiError(e) {
+    switch (e.status) {
+        case 401:
+        case 403:
+            return exports.EXIT.AUTH;
+        case 400:
+            return exports.EXIT.VALIDATION;
+        case 402:
+            return exports.EXIT.INSUFFICIENT_CREDITS;
+        default:
+            return exports.EXIT.GENERIC;
+    }
+}

package/dist/http.js

@@ -36,7 +36,7 @@ async function api(apiUrl, pathname, opts = {}) {
         if (v !== undefined && v !== "")
             url.searchParams.set(k, v);
     }
-    const headers = {};
+    const headers = { ...opts.headers };
     if (opts.key)
         headers.authorization = `Bearer ${opts.key}`;
     if (opts.body !== undefined)

package/dist/jobs.js

@@ -0,0 +1,75 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendJob = appendJob;
+exports.readJobs = readJobs;
+// Local jobs ledger — append-only NDJSON at <config-dir>/jobs.jsonl. `run`
+// appends one line on submit and one on the terminal result; `jobs` reads it
+// back. Best-effort: a ledger write must never crash a run (spec — the ledger
+// is a convenience, not the source of truth; the server owns run state).
+const fs = __importStar(require("node:fs"));
+const config_1 = require("./config");
+/** Append one ledger line. Swallows IO errors — never fails the caller. */
+function appendJob(entry) {
+    try {
+        fs.mkdirSync((0, config_1.configDir)(), { recursive: true, mode: 0o700 });
+        fs.appendFileSync((0, config_1.jobsPath)(), JSON.stringify(entry) + "\n");
+    }
+    catch {
+        // ledger is best-effort; the run already succeeded/failed on its own terms
+    }
+}
+/** Read every ledger line, newest last. Skips malformed lines defensively. */
+function readJobs() {
+    let raw;
+    try {
+        raw = fs.readFileSync((0, config_1.jobsPath)(), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // tolerate a partially-written trailing line
+        }
+    }
+    return out;
+}

package/dist/json-error.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topUpUrl = topUpUrl;
+exports.guardJson = guardJson;
+// Shared --json error emission for the read commands (list/balance/history/
+// tools). Under --json a failing request must put a machine-readable error on
+// stdout (not stderr) and exit with the frozen code; 402 carries top_up_url.
+const exit_1 = require("./exit");
+const http_1 = require("./http");
+function topUpUrl(apiUrl) {
+    return `${apiUrl}/credits`;
+}
+/** Runs `body`; on ApiError under --json, emits the JSON error payload to
+ * stdout and returns the mapped exit code. Non-json failures re-throw so the
+ * cli.ts dispatcher renders them to stderr with the same code. */
+async function guardJson(asJson, apiUrl, body) {
+    try {
+        return await body();
+    }
+    catch (e) {
+        if (asJson && e instanceof http_1.ApiError) {
+            const code = (0, exit_1.exitCodeForApiError)(e);
+            const payload = { error: e.message, exit_code: code };
+            if (e.code)
+                payload.code = e.code;
+            if (code === exit_1.EXIT.INSUFFICIENT_CREDITS)
+                payload.top_up_url = topUpUrl(apiUrl);
+            console.log(JSON.stringify(payload));
+            return code;
+        }
+        throw e;
+    }
+}

package/dist/schema-snapshot.js

@@ -14,7 +14,12 @@ exports.TOOLS_SNAPSHOT = [
             },
             model: { type: "string", enum: ["seedance-2", "kling-3"], default: "seedance-2" },
             quality: { type: "string", enum: ["standard", "pro"], default: "standard" },
-            duration: { type: "number", default: 5, min: 1 },
+            duration: {
+                type: "number",
+                default: 5,
+                min: 1,
+                description: "Video length in seconds. Allowed values depend on model — seedance-2: 4, 5, 6, 8, 10, 12, 15; kling-3: 3, 5, 8, 10, 15.",
+            },
             aspect_ratio: {
                 type: "string",
                 enum: ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"],
@@ -24,6 +29,10 @@ exports.TOOLS_SNAPSHOT = [
             captions: { type: "boolean", default: false },
             caption_style: { type: "string", enum: ["movie", "tiktok"], default: "tiktok" },
             enhance_prompt: { type: "boolean", default: false },
+            influencer: {
+                type: "string",
+                description: "Slug of a saved influencer — the server attaches its portrait + character sheet as references and prepends its appearance description to the prompt.",
+            },
         },
     },
     {
@@ -45,6 +54,10 @@ exports.TOOLS_SNAPSHOT = [
             resolution: { type: "string", enum: ["1k", "2k", "4k"], default: "1k" },
             count: { type: "number", default: 1, min: 1, max: 4 },
             enhance_prompt: { type: "boolean", default: false },
+            influencer: {
+                type: "string",
+                description: "Slug of a saved influencer — the server attaches its portrait + character sheet as references and prepends its appearance description to the prompt.",
+            },
         },
     },
     {
@@ -56,4 +69,13 @@ exports.TOOLS_SNAPSHOT = [
             language: { type: "string", default: "auto" },
         },
     },
+    {
+        name: "create_influencer",
+        description: "Create a reusable, account-bound influencer: a hero portrait + a multi-view character sheet. Flat 20 credits. The prompt is auto-rewritten server-side (always-on).",
+        params: {
+            prompt: { type: "string", required: true },
+            name: { type: "string", required: true, min: 1, maxLength: 60 },
+            slug: { type: "string", maxLength: 40 },
+        },
+    },
 ];

package/dist/types.js

@@ -6,3 +6,7 @@
 // test/parity.test.ts imports core (test-only, relative path) and pins the
 // values that could drift.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDEMPOTENCY_KEY_HEADER = void 0;
+/** Header carrying the client-generated idempotency key on run creation
+ * (mirrors contract.ts IDEMPOTENCY_KEY_HEADER; parity.test.ts pins it). */
+exports.IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";

package/dist/validate.js

@@ -32,6 +32,9 @@ exports.FLAG_FOR = {
     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. */
@@ -49,6 +52,9 @@ function buildToolInput(flags) {
         ["count", "count"],
         ["resolution", "resolution"],
         ["language", "language"],
+        ["name", "name"],
+        ["slug", "slug"],
+        ["influencer", "influencer"],
     ];
     for (const [flag, param] of direct) {
         if (flags[flag] !== undefined)

package/dist/version.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// Package version, read from package.json at runtime. dist/*.js sits one level
+// under the package root (rootDir src → outDir dist), so ../package.json
+// resolves both from the installed npm package and from the repo's built dist.
+// require() (CommonJS build) reads it synchronously with no bundler step.
+exports.VERSION = require("../package.json").version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getagenthook",
-  "version": "0.1.0",
+  "version": "0.2.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",