@jinn-network/client 0.1.1 → 0.1.2-canary.6237288d

package/skills/jinn-operator/SKILL.md

@@ -122,6 +122,91 @@ The automatic faucet may have rate-limited (1 claim per 24 hours per address). O
 - Wait 24 hours and re-run `jinn quickstart`
 - Fund manually: go to https://portal.cdp.coinbase.com/products/faucet, send testnet ETH to the printed master address, then re-run
 
+## Phase 3.5: Opting In to Intent Kinds
+
+After quickstart, the daemon participates in `legacy` (health-check) and `prediction.v0` intents by default. Other intent kinds are **off by default** because they require operator-specific credentials (exchange authorizations, API keys, etc.).
+
+### Generic flow (applies to every intent kind with external deps)
+
+**Always start with `list`.** It tells you what's enabled, what's ready, and for disabled kinds, what running `enable` would need.
+
+```bash
+jinn intents list --human
+```
+
+Example output for a fresh operator:
+```
+kind           enabled   ready   notes
+portfolio.v0   no        no      HL api-wallet not provisioned
+prediction.v0  yes       yes
+```
+
+### Enabling a kind (idempotent state machine)
+
+```bash
+jinn intents enable <kind> [--key=value ...]
+```
+
+The command is idempotent. Rerun the same command until the response has `"status": "ready"`. Intermediate states tell you exactly what to do:
+
+- `"status": "missing_args"` — the envelope lists `required` args. Re-run with them. Shape:
+  ```json
+  {
+    "status": "missing_args",
+    "required": [{"name": "hl-master", "description": "...", "required": true}],
+    "example": {"cli": "jinn intents enable portfolio.v0 --hl-master 0x..."}
+  }
+  ```
+
+- `"status": "waiting_for_external_action"` — the operator needs to do something out-of-band (e.g., approve an api-wallet on an exchange). Show the `action.description` and `action.url` to the operator. When they confirm done, run the command in `nextInvocation.cli`. Shape:
+  ```json
+  {
+    "status": "waiting_for_external_action",
+    "action": {"description": "...", "url": "https://..."},
+    "details": {"apiWalletAddress": "0x..."},
+    "nextInvocation": {"cli": "jinn intents enable <kind> --confirm-approved", "purpose": "..."}
+  }
+  ```
+
+- `"status": "ready"` — the kind is enabled. The daemon will now claim intents of this kind. No further action.
+
+- `"status": "error"` — surface `message` to the operator.
+
+### Disabling
+
+```bash
+jinn intents disable <kind>
+```
+
+Removes the kind from the operator's claim rotation. Preserves any generated key material so a later `enable` doesn't re-initialize exchange approvals.
+
+### Example: enabling portfolio.v0
+
+portfolio.v0 requires a Hyperliquid master account (holds USDC) and an approved HL api-wallet (agent key). The enable flow walks the operator through it:
+
+1. Run list to see what's needed:
+   ```bash
+   jinn intents list --human
+   jinn intents status portfolio.v0 --human
+   ```
+
+2. First invocation generates the api-wallet keypair and returns `waiting_for_external_action` with the wallet address and the HL URL:
+   ```bash
+   jinn intents enable portfolio.v0 --hl-master 0xYOUR_HL_MASTER
+   ```
+
+3. Surface the wallet address and URL to the operator. They approve the address on HL (Settings → API Wallets → Add).
+
+4. Once they confirm, re-run with `--confirm-approved`:
+   ```bash
+   jinn intents enable portfolio.v0 --confirm-approved
+   ```
+   Envelope returns `"status": "ready"`. Config is updated. Daemon will claim future portfolio.v0 requests.
+
+### Runtime guardrail
+
+The daemon checks each impl's readiness before spending gas on a claim transaction. If a portfolio.v0 request arrives and the api-wallet is missing/unapproved, the intent is marked FAILED locally with a reason pointing back to `jinn intents enable portfolio.v0 ...`. No gas wasted.
+
 ## Phase 4: Ongoing Operation
 
 ### Monitoring

package/dist/daemon/restorer.d.ts

@@ -1,19 +0,0 @@
-import type { ExecutionAdapter } from '../adapters/adapter.js';
-import type { Runner } from '../runner/runner.js';
-import type { Store } from '../store/store.js';
-export declare class RestorerLoop {
-    private readonly adapter;
-    private readonly runner;
-    private readonly store;
-    private readonly workingDirectory;
-    private readonly timeoutMs;
-    private readonly daemonApiUrl?;
-    private stopped;
-    private requestIterator;
-    private stopResolve;
-    private stopPromise;
-    constructor(adapter: ExecutionAdapter, runner: Runner, store: Store, workingDirectory?: string, timeoutMs?: number, daemonApiUrl?: string | undefined);
-    processOne(): Promise<boolean>;
-    run(): Promise<void>;
-    stop(): void;
-}

package/dist/daemon/restorer.js

@@ -1,82 +0,0 @@
-import { PermanentError, TransientError } from '../types/index.js';
-import { isRecoverableTransactionError } from '../tx-retry.js';
-export class RestorerLoop {
-    adapter;
-    runner;
-    store;
-    workingDirectory;
-    timeoutMs;
-    daemonApiUrl;
-    stopped = false;
-    requestIterator = null;
-    stopResolve = null;
-    stopPromise;
-    constructor(adapter, runner, store, workingDirectory = '/tmp', timeoutMs = 300000, daemonApiUrl) {
-        this.adapter = adapter;
-        this.runner = runner;
-        this.store = store;
-        this.workingDirectory = workingDirectory;
-        this.timeoutMs = timeoutMs;
-        this.daemonApiUrl = daemonApiUrl;
-        this.stopPromise = new Promise(resolve => {
-            this.stopResolve = resolve;
-        });
-    }
-    async processOne() {
-        if (!this.requestIterator) {
-            this.requestIterator = this.adapter.watchForRequests()[Symbol.asyncIterator]();
-        }
-        const { value: request, done } = await this.requestIterator.next();
-        if (done || !request || !request.requestId)
-            return false;
-        try {
-            await this.adapter.claimRequest(request.requestId);
-        }
-        catch (err) {
-            if (err instanceof PermanentError) {
-                return true;
-            }
-            throw err;
-        }
-        this.store.recordOwnActivity(request.requestId, 'claimed');
-        try {
-            const result = await this.runner.run(request.desiredState, {
-                requestId: request.requestId,
-                workingDirectory: this.workingDirectory,
-                timeoutMs: this.timeoutMs,
-                storePath: this.store.path,
-                daemonApiUrl: this.daemonApiUrl,
-            });
-            await this.adapter.submitResult(request.requestId, result);
-            this.store.recordOwnActivity(request.requestId, 'delivered');
-        }
-        catch (err) {
-            if (!(err instanceof TransientError)) {
-                console.error(`[restorer] Failed to restore ${request.requestId}:`, err);
-            }
-        }
-        return true;
-    }
-    async run() {
-        while (!this.stopped) {
-            try {
-                await this.processOne();
-            }
-            catch (err) {
-                if (err instanceof TransientError) {
-                    await Promise.race([new Promise(r => setTimeout(r, 5000)), this.stopPromise]);
-                }
-                else {
-                    console.error('[restorer] Error:', err);
-                    const delayMs = isRecoverableTransactionError(err) ? 15_000 : 10_000;
-                    await Promise.race([new Promise(r => setTimeout(r, delayMs)), this.stopPromise]);
-                }
-            }
-        }
-    }
-    stop() {
-        this.stopped = true;
-        this.stopResolve?.();
-    }
-}
-//# sourceMappingURL=restorer.js.map

package/dist/daemon/restorer.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"restorer.js","sourceRoot":"","sources":["../../src/daemon/restorer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAC;AAG/D,MAAM,OAAO,YAAY;IAOJ;IACA;IACA;IACA;IACA;IACA;IAXX,OAAO,GAAG,KAAK,CAAC;IAChB,eAAe,GAA6C,IAAI,CAAC;IACjE,WAAW,GAAwB,IAAI,CAAC;IACxC,WAAW,CAAgB;IAEnC,YACmB,OAAyB,EACzB,MAAc,EACd,KAAY,EACZ,mBAA2B,MAAM,EACjC,YAAoB,MAAM,EAC1B,YAAqB;QALrB,YAAO,GAAP,OAAO,CAAkB;QACzB,WAAM,GAAN,MAAM,CAAQ;QACd,UAAK,GAAL,KAAK,CAAO;QACZ,qBAAgB,GAAhB,gBAAgB,CAAiB;QACjC,cAAS,GAAT,SAAS,CAAiB;QAC1B,iBAAY,GAAZ,YAAY,CAAS;QAEtC,IAAI,CAAC,WAAW,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC,EAAE;YACvC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC1B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QACjF,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;QACnE,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS;YAAE,OAAO,KAAK,CAAC;QAEzD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAE3D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE;gBACzD,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;gBAC1B,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC,CAAC,CAAC;YAEH,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC3D,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,CAAC,GAAG,YAAY,cAAc,CAAC,EAAE,CAAC;gBACrC,OAAO,CAAC,KAAK,CAAC,gCAAgC,OAAO,CAAC,SAAS,GAAG,EAAE,GAAG,CAAC,CAAC;YAC3E,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,GAAG;QACP,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;oBAClC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBAChF,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;oBACxC,MAAM,OAAO,GAAG,6BAA6B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;oBACrE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;gBACnF,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;IACvB,CAAC;CACF"}