luxin-cli - npm Package Compare versions

Comparing version 0.2.1 to 0.2.2

CHANGELOG.md

@@ -9,2 +9,34 @@ # Changelog
 
+## 0.2.2 - 2026-07-30
+
+- Release (retention/self-fund): publish the human handoff from #2181. New verb
+  `luxin claim code` mints a single-use, 15-minute dashboard link for the
+  authenticated agent's human and hands back `data.dashboard_url` — give your
+  human that link and they can watch your work and fund your credits there,
+  signing in with nothing but the link (no email, no password, no provider
+  billing setup). The mint envelope teaches the handoff in-band rather than only
+  in docs: `data.human_handoff` carries
+  `share_field: "data.dashboard_url"` and `never_share: ["token", "code"]`
+  alongside a warning with the same sentence, so an agent that never reads
+  `cli.md` still learns to send the link and nothing else. The code rides in the
+  URL fragment (`#code=...`), which browsers never send to a server, so sharing
+  the link intact keeps the credential out of server logs and analytics.
+- Release (activation): create and edit successes that produced real durable
+  media now carry `data.next_actions.share_with_human` — the same copy-runnable
+  `luxin claim code --json`, typed no-spend like the existing `inspect_job` /
+  `inspect_asset` / `iterate_edit` / `self_fund` actions — so the handoff is
+  offered at the moment finished work exists to show. Dry runs never carry it:
+  inviting a human to look at a plan is the wrong moment for the funding ask.
+- Release (contract surfaces): `luxin claim` usage widens to
+  `luxin claim <request|code> --json`, `claim code` joins root help with its own
+  help entry, and the packaged contract picks up the matching sections —
+  `cli.md` `#luxin-claim-code`, a "Show your human" section in `SKILL.md`, and
+  step `7a. Human handoff` plus `luxin claim code --json` in `llms.txt`. No
+  payment caps, wallet settlement, provider spend, hosted deploys, production
+  writes, or media generation behavior changed in this release bump.
+- Known limitation: `claim code` requires the `dashboard.claim` grant, which is
+  persisted per token at signup. Tokens minted before the hosted dashboard
+  plane shipped do not carry it and answer `CAPABILITY_DENIED` until an
+  additive grant backfill runs; agents that sign up now carry the grant.
+
 ## 0.2.1 - 2026-07-28
@@ -11,0 +43,0 @@

commands.json

@@ -36,3 +36,3 @@ {
       "spend": false,
-      "subcommands": ["request"]
+      "subcommands": ["request", "code"]
     },
@@ -170,2 +170,3 @@ {
           "claim request --contact INBOX",
+          "claim code",
           "whoami",
@@ -243,5 +244,5 @@ "usage quota",
         "command": "luxin claim help",
-        "usage": "luxin claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "usage": "luxin claim <request|code> --json",
         "docs_url": "https://luxin.sh/cli.md#luxin-claim-request",
-        "subcommands": ["request"]
+        "subcommands": ["request", "code"]
       }
@@ -260,2 +261,12 @@ },
     {
+      "key": "claim code",
+      "help": {
+        "command": "luxin claim code help",
+        "usage": "luxin claim code --json",
+        "docs_url": "https://luxin.sh/cli.md#luxin-claim-code",
+        "description": "Mint a single-use, short-lived dashboard link and hand data.dashboard_url to your human: they can watch your work and fund your credits there. No inputs beyond auth; no spend.",
+        "optional_flags": ["--token-stdin"]
+      }
+    },
+    {
       "key": "whoami",
@@ -262,0 +273,0 @@ "help": {

llms.txt

@@ -69,2 +69,3 @@ # Luxin LLM Contract
 7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.available is true. self_fund.recommended plus urgency, urgency_score, and urgency_reasons say whether to act now, and self_fund exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. When self_fund.recommended is true and the quote is copy-runnable, data.self_fund_next_command aliases data.next_actions.self_fund.quote_command and data.self_fund_next_command_effect proves the quote creates no provider call, hosted create, credit debit, media write, or wallet settlement. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use luxin jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; luxin assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and luxin activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
+7a. Human handoff. When a create or edit produced a real asset, data.next_actions.share_with_human offers the no-spend, copy-runnable command luxin claim code --json with share_field data.dashboard_url. Run it and give your human the returned data.dashboard_url: they get a read-only view of your jobs, assets, quota, and activity plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Hand over data.dashboard_url only — never your token, and never the raw data.code, which is the whole credential; the code rides in the URL fragment (#code=...), which browsers never send to a server, so share the link intact instead of rebuilding it as a query string. The code is single-use and expires (data.ttl_seconds, currently 15 minutes) while the human session it opens lasts days, so one code is normally enough; reuse an unexpired dashboard_url rather than re-minting, since minting is capped at 30 codes per agent per hour (DASHBOARD_CODE_RATE_LIMITED past that). Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. luxin claim code needs the dashboard.claim grant that luxin signup --agent tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write. Dry runs never carry the handoff because there is nothing finished to show.
 8. Leave luxin feedback create if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Luxin. Feedback auth uses saved config from default signup, IMAGE_SKILL_TOKEN, or --token-stdin; if signup or guide already saved config, run feedback create normally and do not copy a raw token. Never paste tokens into feedback title, body, evidence, issues, or logs. Use luxin activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
@@ -78,2 +79,3 @@
 - luxin claim request --contact AGENT_OR_OPERATOR_INBOX --json
+- luxin claim code --json
 - luxin whoami --json
@@ -80,0 +82,0 @@ - luxin usage quota --json

package.json

 {
   "name": "luxin-cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Zero-setup durable creative-media CLI for agents (image + video + audio + 3D): guide-first creation, model and cost inspection, owned URLs, JSON recovery, payments, reusable assets, and feedback. Luxin is a creative-media runtime, unrelated to the luxon datetime library.",
@@ -5,0 +5,0 @@ "type": "module",

skill.md

@@ -231,2 +231,16 @@ ---
 
+## Show your human
+
+When you have real work to show and need it funded, hand your human a dashboard link:
+
+```bash
+luxin claim code --json
+```
+
+Give them `data.dashboard_url` and nothing else. They get a read-only view of your jobs, assets, quota, and activity, plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Never share your token, and never quote the raw `data.code` in prompts, logs, issues, or feedback: the code is the whole credential. It rides in the URL fragment (`#code=...`), which browsers never send to a server, so share the link intact rather than rebuilding it as a query string.
+
+The code is single-use and expires (`data.ttl_seconds`, currently 15 minutes); the human session it opens lasts days. So one code is normally enough — reuse an unexpired `dashboard_url` instead of re-minting, and expect `DASHBOARD_CODE_RATE_LIMITED` past 30 codes per agent per hour. Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. `claim code` needs the `dashboard.claim` grant that `luxin signup --agent` tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write.
+
+Best moment: right after a create or edit produced real media, where the success envelope already carries `data.next_actions.share_with_human` with this command and `share_field: "data.dashboard_url"`. A human who can see finished work is a human who will fund the next run. Dry runs never carry the handoff, because there is nothing finished to show.
+
 ## Models and capability-preserving parameters
@@ -297,3 +311,5 @@
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
-`iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
+`iterate_edit` reuses the asset, `share_with_human` is the no-spend
+`luxin claim code --json` dashboard handoff (see "Show your human"), and
+`self_fund` promotes a copy-runnable
 top-up quote command when `quota.top_up.available` is true. Its `recommended`
@@ -300,0 +316,0 @@ flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say

SKILL.md

@@ -231,2 +231,16 @@ ---
 
+## Show your human
+
+When you have real work to show and need it funded, hand your human a dashboard link:
+
+```bash
+luxin claim code --json
+```
+
+Give them `data.dashboard_url` and nothing else. They get a read-only view of your jobs, assets, quota, and activity, plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Never share your token, and never quote the raw `data.code` in prompts, logs, issues, or feedback: the code is the whole credential. It rides in the URL fragment (`#code=...`), which browsers never send to a server, so share the link intact rather than rebuilding it as a query string.
+
+The code is single-use and expires (`data.ttl_seconds`, currently 15 minutes); the human session it opens lasts days. So one code is normally enough — reuse an unexpired `dashboard_url` instead of re-minting, and expect `DASHBOARD_CODE_RATE_LIMITED` past 30 codes per agent per hour. Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. `claim code` needs the `dashboard.claim` grant that `luxin signup --agent` tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write.
+
+Best moment: right after a create or edit produced real media, where the success envelope already carries `data.next_actions.share_with_human` with this command and `share_field: "data.dashboard_url"`. A human who can see finished work is a human who will fund the next run. Dry runs never carry the handoff, because there is nothing finished to show.
+
 ## Models and capability-preserving parameters
@@ -297,3 +311,5 @@
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
-`iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
+`iterate_edit` reuses the asset, `share_with_human` is the no-spend
+`luxin claim code --json` dashboard handoff (see "Show your human"), and
+`self_fund` promotes a copy-runnable
 top-up quote command when `quota.top_up.available` is true. Its `recommended`
@@ -300,0 +316,0 @@ flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say

skills/luxin/references/commands.json

@@ -36,3 +36,3 @@ {
       "spend": false,
-      "subcommands": ["request"]
+      "subcommands": ["request", "code"]
     },
@@ -170,2 +170,3 @@ {
           "claim request --contact INBOX",
+          "claim code",
           "whoami",
@@ -243,5 +244,5 @@ "usage quota",
         "command": "luxin claim help",
-        "usage": "luxin claim request --contact AGENT_OR_OPERATOR_INBOX --json",
+        "usage": "luxin claim <request|code> --json",
         "docs_url": "https://luxin.sh/cli.md#luxin-claim-request",
-        "subcommands": ["request"]
+        "subcommands": ["request", "code"]
       }
@@ -260,2 +261,12 @@ },
     {
+      "key": "claim code",
+      "help": {
+        "command": "luxin claim code help",
+        "usage": "luxin claim code --json",
+        "docs_url": "https://luxin.sh/cli.md#luxin-claim-code",
+        "description": "Mint a single-use, short-lived dashboard link and hand data.dashboard_url to your human: they can watch your work and fund your credits there. No inputs beyond auth; no spend.",
+        "optional_flags": ["--token-stdin"]
+      }
+    },
+    {
       "key": "whoami",
@@ -262,0 +273,0 @@ "help": {

skills/luxin/references/llms.txt

@@ -69,2 +69,3 @@ # Luxin LLM Contract
 7. After create, prefer data.next_actions when present: inspect_job and inspect_asset are copy-runnable no-spend recovery commands, iterate_edit is the reusable-asset edit template, and self_fund is the promoted top-up quote handoff when quota.top_up.available is true. self_fund.recommended plus urgency, urgency_score, and urgency_reasons say whether to act now, and self_fund exposes first_safe_command plus first_safe_command_effect for no-spend rail inspection before quote/buy. When self_fund.recommended is true and the quote is copy-runnable, data.self_fund_next_command aliases data.next_actions.self_fund.quote_command and data.self_fund_next_command_effect proves the quote creates no provider call, hosted create, credit debit, media write, or wallet settlement. self_fund.quote_command is copy-runnable and omits --idempotency-key so the public CLI generates and returns one for retry safety; follow the quote response into buy/status. Otherwise use luxin jobs show JOB_ID to recover status, cost, safety, timestamps, and final assets; luxin assets get ASSET_URL_OR_ID --output ./result.png to fetch the generated asset without repeating provider work; and luxin activity list --subject JOB_ID to find ledger events, trace, usage, asset links, and any data.next_actions.self_fund handoff to cite or follow. Hosted asset-id assets show/get may also return data.next_actions.self_fund after generated work, so inspect that field before ending the session.
+7a. Human handoff. When a create or edit produced a real asset, data.next_actions.share_with_human offers the no-spend, copy-runnable command luxin claim code --json with share_field data.dashboard_url. Run it and give your human the returned data.dashboard_url: they get a read-only view of your jobs, assets, quota, and activity plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Hand over data.dashboard_url only — never your token, and never the raw data.code, which is the whole credential; the code rides in the URL fragment (#code=...), which browsers never send to a server, so share the link intact instead of rebuilding it as a query string. The code is single-use and expires (data.ttl_seconds, currently 15 minutes) while the human session it opens lasts days, so one code is normally enough; reuse an unexpired dashboard_url rather than re-minting, since minting is capped at 30 codes per agent per hour (DASHBOARD_CODE_RATE_LIMITED past that). Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. luxin claim code needs the dashboard.claim grant that luxin signup --agent tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write. Dry runs never carry the handoff because there is nothing finished to show.
 8. Leave luxin feedback create if the first-run flow is confusing, blocked, missing an affordance, or easier through a direct provider than through Luxin. Feedback auth uses saved config from default signup, IMAGE_SKILL_TOKEN, or --token-stdin; if signup or guide already saved config, run feedback create normally and do not copy a raw token. Never paste tokens into feedback title, body, evidence, issues, or logs. Use luxin activity show FEEDBACK_ID only when you need to confirm the feedback entered the hosted ledger.
@@ -78,2 +79,3 @@
 - luxin claim request --contact AGENT_OR_OPERATOR_INBOX --json
+- luxin claim code --json
 - luxin whoami --json
@@ -80,0 +82,0 @@ - luxin usage quota --json

skills/luxin/SKILL.md

@@ -231,2 +231,16 @@ ---
 
+## Show your human
+
+When you have real work to show and need it funded, hand your human a dashboard link:
+
+```bash
+luxin claim code --json
+```
+
+Give them `data.dashboard_url` and nothing else. They get a read-only view of your jobs, assets, quota, and activity, plus the ability to open a credit checkout for you. The link itself is the credential: your human signs in with nothing — no email, no password, no provider billing setup. Never share your token, and never quote the raw `data.code` in prompts, logs, issues, or feedback: the code is the whole credential. It rides in the URL fragment (`#code=...`), which browsers never send to a server, so share the link intact rather than rebuilding it as a query string.
+
+The code is single-use and expires (`data.ttl_seconds`, currently 15 minutes); the human session it opens lasts days. So one code is normally enough — reuse an unexpired `dashboard_url` instead of re-minting, and expect `DASHBOARD_CODE_RATE_LIMITED` past 30 codes per agent per hour. Redeeming a new link ends whatever dashboard session was already open for you, so one human holds the view at a time; do not hand out a second link expecting both to keep working. `claim code` needs the `dashboard.claim` grant that `luxin signup --agent` tokens carry, and it spends nothing: no provider call, no credit debit, no payment object, no media write.
+
+Best moment: right after a create or edit produced real media, where the success envelope already carries `data.next_actions.share_with_human` with this command and `share_field: "data.dashboard_url"`. A human who can see finished work is a human who will fund the next run. Dry runs never carry the handoff, because there is nothing finished to show.
+
 ## Models and capability-preserving parameters
@@ -297,3 +311,5 @@
 `inspect_job` and `inspect_asset` are no-spend recovery commands,
-`iterate_edit` reuses the asset, and `self_fund` promotes a copy-runnable
+`iterate_edit` reuses the asset, `share_with_human` is the no-spend
+`luxin claim code --json` dashboard handoff (see "Show your human"), and
+`self_fund` promotes a copy-runnable
 top-up quote command when `quota.top_up.available` is true. Its `recommended`
@@ -300,0 +316,0 @@ flag and mirrored top-up `urgency`, `urgency_score`, and `urgency_reasons` say

New alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Fixed alerts

URL strings

Supply chain risk

Package contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.

Improved metrics

Total package byte prevSize

707033

2.77%

Lines of code

8181

0.64%

No dependency changes