@perkos/agent-sdk 0.7.0 → 0.8.0-rc.1

package/docs/TESTNET_QUICKSTART.md

@@ -0,0 +1,123 @@
+# Role-separated agent onboarding — QA candidate
+
+This guide describes the QA candidate, not a published npm release. The role-separated
+SDK/committed-evaluation flow has completed controlled STX and sBTC testnet jobs; this
+does not certify a live Hermes installation or external adoption.
+Use Node.js 22 and the reviewed QA commit. Do not point it at mainnet.
+The app's default deployments, production and the published package are unchanged.
+
+## Roles and custody
+
+- Buyer: owns criteria, creates the job, sets its budget, funds escrow and assigns a provider.
+- Provider: owns its wallet, performs the work and submits the committed evidence manifest.
+- Evaluator service: verifies chain state and downloaded evidence, then records its decision.
+- Human appeal authority: handles disputes; it is not installed in either participant agent.
+
+Create separate testnet wallets with your custody provider. Keep each key in its own signer
+boundary, fund only the required test tokens and STX gas, and never share the evaluator key.
+The example imports an **operator-selected absolute module path** exporting a `PerkOSSigner`
+named `signer`. Do not let an LLM or external job select that module. Its implementation must
+restrict network, contracts, operation, nonce and gas fees and durably account for wallet spending.
+SDK spending policies are per process and do not replace persistent custody limits.
+The separate [Hermes MCP adapter](HERMES_MCP.md) defaults to read/prepare only. Optional
+[bounded custody delegation](HERMES_CUSTODY.md) is a QA source candidate for wallet-enabled
+actions; it still requires review, deployment, Linux isolation and actual Hermes E2E validation.
+Provider MCP may additionally opt into public QA evaluation admission after its confirmed
+submission; see [the exact tools and operator flag](HERMES_MCP.md#optional-provider-evaluation-admission).
+The CLI walkthrough below remains a separate operator-driven example, not proof of Hermes autonomy.
+
+## Install and preview
+
+From the reviewed SDK source checkout:
+
+```bash
+npm ci
+npm run verify
+npm run quickstart:testnet
+```
+
+The last command defaults to offline preview; it does not load a signer or call a network.
+For clean-consumer testing, build and pack the candidate, then install that tarball in a
+separate project with Node 22 and `tsx`. Do not publish or overwrite npm 0.7.1.
+
+## Supply real job inputs
+
+Keep a JSON config **outside Git**, with one copy for each role. Required fields:
+
+| Field | Value |
+|---|---|
+| network / asset | `testnet` / `stx` or `sbtc` |
+| role | `client` or `provider` |
+| client / provider / evaluator / treasury | Four distinct real testnet principals; evaluator and treasury must match QA policy |
+| amount | Decimal string in micro-STX or satoshis; example cap 100000 or 1000 respectively |
+| expiredAt | Future **Stacks block height**, not burn height or Unix time |
+| description | Real ASCII work description, at most 428 characters |
+| acceptanceCriteria | Array of `{ id, requirement, verification }` fixed by the buyer before creation |
+| jobId | Confirmed job ID, required after creation |
+| evidence | Provider's real `{ id, uri, sha256, mediaType, sizeBytes }` manifest |
+| agentName | Optional real participant name |
+
+Use the configured QA evaluator's evidence origin allowlist. Automatic review initially supports
+up to five HTTPS UTF-8 text/plain or application/json files, 8192 bytes per file, 16000 bytes total.
+Hash the exact downloaded bytes; no fake URLs or invented deliverables. Public manifests and
+chain commitments must never contain secrets. Preserve the original criteria file for both roles.
+
+## Run one step at a time
+
+Set `PERKOS_RUN_CONFIG`, `PERKOS_JOURNAL` and `PERKOS_SIGNER_MODULE` to absolute paths outside Git.
+Use a dedicated journal per role and run. Enable `PERKOS_CONFIRM_TESTNET_BROADCAST=yes` only for
+the intended operation. Funding and submission also require
+`PERKOS_ACCEPT_SERVICE_FEE=200bps-net-after-evaluation`.
+
+```bash
+PERKOS_ACTION=register npm run quickstart:testnet
+PERKOS_ACTION=create npm run quickstart:testnet
+```
+
+Both participants register using their own process. Only the buyer creates. Copy the confirmed
+`(ok uN)` job ID from creation into both role configs, then execute separately:
+
+1. Buyer: `set-budget`, then `fund`, then `assign`.
+2. Provider: do the actual work, prepare the real evidence manifest, then `submit`.
+3. Either role: `evaluate` against an explicitly configured `PERKOS_EVALUATOR_URL` QA origin.
+4. Either role: `status`. It is read-only and needs no signer or broadcast opt-in.
+5. Buyer: `finalize` only after decision-pending, no appeal, and current burn height strictly
+   greater than the appeal deadline. Disputes require the appeal workflow, not bypassing this gate.
+
+A `202` response means admitted, not approved. Poll the returned evaluation ID at
+`GET /v1/evaluations/{id}` and inspect the on-chain job. A recorded decision does not transfer
+escrow. On finalization, independently verify the 98/2 provider/treasury split (or evaluated
+rejection refund), zero escrow and reputation sync. Gas is additional, paid by each transaction signer.
+The 2% fee is earned on evaluation and stays in escrow until settlement; no extra appeal fee is added.
+
+## Commitments without new contracts
+
+`prepareEvaluationJob(input)` returns the description plus a versioned SHA-256 criteria marker.
+`prepareEvaluationSubmission(input)` returns a 36-byte deliverable: ASCII `ny1:` and the raw
+32-byte evidence digest, fitting existing `(buff 64)` contracts.
+
+Both use fixed projected JSON fields, lexicographically sorted keys, ordered arrays, UTF-8 and
+distinct hash domains. Criteria bind network/asset/contract/client/evaluator/description.
+Evidence additionally binds job ID, provider and criteria hash. Do not reorder arrays, normalize
+text or change manifests after signing. `evaluationJobId` derives a deterministic job-scoped
+request identifier; it is **not** a credential.
+
+Hashes protect manifest integrity, not evidence truth. Only the on-chain client can commit the
+criteria and only the assigned provider can submit the evidence. Public HTTP callers may trigger
+verification of those exact commitments, but cannot change criteria, spend participant wallets
+or force the evaluator to approve.
+
+## Recovery and limitations
+
+The append-only mode-600 journal records an attempt before signing and stores the txid before
+confirmation. Repeating an identical invocation confirms that txid instead of signing again.
+Changed action inputs, a stale lock, malformed journal or ambiguous attempt fail closed.
+Never delete checkpoints to force a retry: reconcile the wallet nonce and transaction history first.
+Ambiguous signing failures require operator reconciliation; no exactly-once
+network guarantee is claimed. A dry preview is not an on-chain E2E test.
+
+The evaluator public writer defaults off; controlled QA has enabled bounded admission and
+passed database/restart and two-role STX/sBTC E2E gates. Isolated live Hermes integration,
+x402-protected API walkthrough and recorded demo remain separate gates.
+The existing x402/MPP clients are separate from this escrow evaluation trigger;
+this route does not introduce another payment or imply x402 coverage was tested here.

package/docs/VALIDATION_AND_RELEASE.md

@@ -0,0 +1,82 @@
+# Hermes validation and release boundary
+
+## What was verified
+
+On 2026-09-08 UTC, one **internal, operator-supervised Stacks testnet** sBTC job completed
+using real Hermes participants, the SDK/MCP tools, isolated policy signers and Nayori's evaluator.
+This is evidence for one scenario, not certification of all workflows or external onboarding.
+
+| Check | Observed result |
+| --- | --- |
+| SDK source | `fc0537477fda819fa9cce8e74e543be0d49ea3a4` on QA |
+| Contract / job | `ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5.sbtc-commerce-v5`, job 14 |
+| Participants | Existing registered agents, separate buyer/provider/evaluator roles |
+| Workflow | Create → budget → fund → assign → actual work → submit → evaluate → finalize |
+| Work | Compute 23 + 19 and explain; actual result 42 with an explanation |
+| Outcome | Completed; zero escrow; exactly 980 atomic sBTC to provider and 20 to treasury |
+| Reputation | One completed job, no disputed job; no pending synchronization |
+| Confirmation | Finalization in burn 14234; six-burn custody gate passed at 14240 |
+
+Public chain evidence:
+
+- [Submission](https://explorer.hiro.so/txid/0x8c99de7f560e82da0483875677ab2de3370403e2a617dff445a77cff40f0da31?chain=testnet)
+- [Evaluator approval](https://explorer.hiro.so/txid/0x2806cebb488794c6a8ff63bf9f437978dc7e492254974c3f06d400381b7a1f27?chain=testnet)
+- [Final settlement, Stacks block 288396](https://explorer.hiro.so/txid/0x382e05645560acbd822f573cab6e32579ad1d8ad3d1598916f132b28b86cce4c?chain=testnet)
+
+No new registration was performed in this cycle: existing records were verified and reused.
+New developers must still follow [registration](EXISTING_AGENT.md); do not repeat registration
+for an already active identity simply to match a video. Use your own agent, LLM and signer.
+Do not send funds to the addresses in this historical evidence.
+
+## Published package versus tested source
+
+| Distribution | Boundary |
+| --- | --- |
+| npm `@perkos/agent-sdk@0.7.1` | Published v5/v4 baseline; does not include the local QA Hermes/custody/fee additions |
+| Reviewed QA source above | Tested v6/v5 opt-in fee path, local Hermes MCP, custody and evaluation admission |
+| Historical QA tarball used in the lifecycle | Reports version 0.7.1; source commit and artifact integrity distinguish it from npm |
+| Current source candidate | 0.8.0-rc.1, not published; see [candidate notes](RELEASE_0.8.0_RC1.md) |
+
+Do not publish the candidate over 0.7.1 or describe it as an npm-only installation test. Use
+the [exact-artifact installation procedure](HERMES_MCP.md), never an unpinned financial `npx`.
+
+Before external distribution: review and merge the release changes, assign a new package version,
+run the SDK gate, pack and inspect its allowlisted contents, then install that exact artifact in
+a clean consumer. Verify imports, binaries and both role guides. Publish only after separate
+release approval; verify registry integrity and repeat clean installation from the published
+version. A QA merge, npm publication and production deployment are separate events.
+
+## Report three independent outcomes
+
+1. **Conversation:** Hermes must explicitly report `completed=true`; a `type: result` envelope
+   alone is insufficient. A tool may have executed even when the conversation stopped at its limit.
+2. **Operation:** preserve the actual intent, txid and journal; query the existing operation after
+   timeout or interruption. Never re-sign merely because the conversation did not complete.
+3. **Economics:** independently verify canonical success, confirmation depth, terminal job state,
+   zero escrow, exact unique transfers and reputation. Evaluator approval is not payment.
+
+Count persisted LLM attempts separately from received responses. Missing usage means **unknown**,
+not zero. Track buyer, provider and evaluator independently; a configured maximum is a bound,
+not an observed call count or bill. This cycle observed 26 Hermes calls; evaluator usage is bounded
+by four calls but its exact count is not established by this report.
+
+## Two different evidence hashes
+
+The evaluator artifact/decision uses SHA-256 of the canonical evidence list. The SDK's versioned
+submission commitment additionally binds domain, network, contract, job, roles and criteria.
+These hashes are intentionally different. Recompute each from its own input: compare the
+SDK commitment to `submit-work`/the job deliverable and the manifest hash to the evaluator
+artifact/`record-decision`. Verify the public explanation digest and fetched evidence bytes too.
+Never accept a mismatched hash by copying the expected value from the response under test.
+
+## Still outside this proof
+
+- Fresh npm-only installation, new-agent registration in this cycle, and the developer video.
+- Autonomous operation from one instruction without the operator's staged gates.
+- The separate x402/MPP resource-purchase workflow; local QA MCP does not purchase x402.
+- Other assets, rejection/appeal/recovery scenarios, or production fee activation.
+- External security review or independent adoption: these participants are team-operated testnet actors.
+
+Continue with the [buyer](HERMES_BUYER.md), [provider](HERMES_PROVIDER.md) and
+[checkpoint](HERMES_CHECKPOINTS.md) manuals. Every new funded scenario requires its own reviewed
+permissions and budget; never reuse this completed job's authorization.

package/docs/WALLET_SIGNER_SETUP.md

@@ -0,0 +1,52 @@
+# Operator-owned wallet and signer preparation
+
+This is a separate operator checklist, **not a Nayori wallet-generation or custody service**.
+Your existing agent and LLM are already running. Return to [agent onboarding](EXISTING_AGENT.md)
+after preparing a signer. Nayori never needs your private key or model-provider credentials.
+
+## Existing wallet or new wallet
+
+Reuse a dedicated testnet signer if it meets these controls. Otherwise create a dedicated wallet
+using your reviewed Stacks-compatible wallet tooling or a separately maintained Stacks.js operator
+utility. Verify the dependency/version and network; do not ask an LLM to invent a key or use a
+public test fixture. Keep generation and recovery outside the Nayori SDK and agent's tool set.
+
+1. Store the key in your own protected signer storage, outside repositories and agent-readable
+   files. Encrypt backups under operator control. A mode-0600 file alone is not an encrypted backup.
+2. Verify restoration derives the same public testnet address before funding. Never show the key
+   or recovery phrase in tickets, prompts, logs, terminal recordings or documentation.
+3. Give each independently operated buyer/provider a separate identity and signer boundary.
+   Keep transaction sender and the intended registered metadata wallet aligned; registry ownership
+   follows `creator` (transaction sender), not an arbitrary metadata wallet.
+4. Fund only the test assets and STX network fees needed for the authorized test. Do not send
+   mainnet assets to an example/fixture or assume a displayed testnet balance is spendable mainnet value.
+
+## Human-approved or autonomous signatures
+
+- A browser wallet can request human approval through the SDK's browser signer interface.
+- An autonomous agent requests a bounded operation from **your own signer service**. An
+  operator-maintained Stacks.js implementation can validate, construct and sign transactions.
+  This library option is not a turnkey managed signing service supplied by Nayori.
+- Integrate your signer through the documented `PerkOSSigner` interface or the reviewed QA
+  custody bridge. A callback that loads a key in the LLM's process is not an isolation boundary.
+
+Before enabling autonomous signing, enforce:
+
+- Authenticated caller and role; allowed network, contracts, functions and recipients.
+- Explicit per-operation amount, total budget, expiry, asset and STX gas caps.
+- Exact arguments/post-conditions; no arbitrary transaction bytes or module paths selected by an LLM.
+- Separate OS identity/process and private mounts; no shared key access, sudo or Docker socket.
+- Durable intent/nonce/txid journal and serialized use of one wallet across workers.
+- Stop on ambiguous signing/broadcast; inspect chain/mempool before retrying, never delete the journal.
+- An operator-controlled disable switch; test denied actions with signing off first.
+
+SDK spending policies are per-process checks, not a replacement for persistent signer-side
+authorization. The candidate [custody guide](HERMES_CUSTODY.md) documents a restricted QA example;
+it is not a general-purpose production custody service or externally audited wallet manager.
+
+## Safe handoff to the agent
+
+Provide only public network/identity/configuration and the restricted tool or authenticated IPC
+entry point. Keep signer credentials out of prompts and tool arguments. Prove that an allowed
+testnet registration can be requested, a forbidden role/action is denied and the agent cannot
+read key material. Then continue with [registration and confirmation](EXISTING_AGENT.md#4-register-and-verify-the-agent).

package/examples/service-fees.ts

@@ -0,0 +1,36 @@
+import {
+  PerkOSClient,
+  quoteServiceFee,
+  type AmountLike,
+  type PaymentAsset,
+} from "../src/index.js";
+
+/** Signer-free report. It neither grants consent nor broadcasts a transaction. */
+export async function inspectEarnedServiceFee(
+  client: PerkOSClient,
+  asset: PaymentAsset,
+  jobId: AmountLike
+) {
+  if (!client.supportsServiceFees(asset))
+    return { kind: "no-service-fee-generation" as const };
+  const job = await client.getJob(asset, jobId);
+  if (!job) throw new Error("Job not found");
+  const fees = await client.getJobServiceFee(asset, jobId);
+  const quote = quoteServiceFee(job.budget);
+  return {
+    kind: "earned-service-fee" as const,
+    asset,
+    jobId: job.id.toString(),
+    gross: quote.gross.toString(),
+    potentialFee: quote.fee.toString(),
+    netIfEvaluated: (fees.waiver ? quote.gross : quote.net).toString(),
+    treasury: fees.treasury,
+    chargedFee: (fees.settlement?.chargedFee ?? 0n).toString(),
+    refundedFee: (fees.settlement?.refundedFee ?? 0n).toString(),
+    refundOutstanding:
+      !!fees.waiver &&
+      !!fees.settlement &&
+      fees.settlement.chargedFee > fees.settlement.refundedFee,
+    gas: "Separate STX network fee",
+  };
+}

package/examples/testnet-journal.ts

@@ -0,0 +1,57 @@
+import { closeSync, constants, fstatSync, fsyncSync, openSync, readFileSync, writeSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute } from "node:path";
+
+type Entry = { key: string; intent: string; state: "attempting" | "broadcast"; txid?: string };
+
+/** Append-only journal; caller must hold its exclusive lock. Keep outside Git. */
+export class QuickstartJournal {
+  private readonly fd: number;
+  private readonly entries: Entry[];
+  constructor(path: string) {
+    if (!isAbsolute(path)) throw new Error("journal_absolute_path_required");
+    this.fd = openSync(path, constants.O_RDWR | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+    const stat = fstatSync(this.fd);
+    if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.nlink !== 1 || stat.size > 1_048_576 ||
+        (process.getuid && stat.uid !== process.getuid())) {
+      closeSync(this.fd); throw new Error("unsafe_journal");
+    }
+    try {
+      this.entries = readFileSync(this.fd, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line) as Entry);
+      if (this.entries.some(item => !item || typeof item.key !== "string" || !/^[0-9a-f]{64}$/.test(item.intent) ||
+          !["attempting", "broadcast"].includes(item.state) ||
+          (item.state === "broadcast" && !/^0x[0-9a-f]{64}$/.test(item.txid ?? "")))) throw new Error("invalid_journal");
+    } catch { closeSync(this.fd); throw new Error("journal_requires_reconciliation"); }
+  }
+  close() { closeSync(this.fd); }
+  lookup(key: string, intent: string): Entry | undefined {
+    const entries = this.entries.filter(item => item.key === key);
+    if (entries.some(item => item.intent !== intent)) throw new Error("journal_intent_mismatch");
+    return entries.at(-1);
+  }
+  append(entry: Entry) {
+    const bytes = Buffer.from(JSON.stringify(entry) + "\n");
+    let offset = 0;
+    while (offset < bytes.length) offset += writeSync(this.fd, bytes, offset);
+    fsyncSync(this.fd); this.entries.push(entry);
+  }
+}
+export function intentHash(value: unknown): string {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export async function checkpointedTransaction(
+  journal: QuickstartJournal, key: string, intent: string, send: () => Promise<string>,
+): Promise<string> {
+  const prior = journal.lookup(key, intent);
+  if (prior) {
+    if (prior.state !== "broadcast" || !/^0x[0-9a-f]{64}$/.test(prior.txid ?? "")) {
+      throw new Error("ambiguous_attempt_requires_reconciliation");
+    }
+    return prior.txid!;
+  }
+  journal.append({ key, intent, state: "attempting" });
+  const txid = await send();
+  if (!/^0x[0-9a-f]{64}$/.test(txid)) throw new Error("invalid_txid_requires_reconciliation");
+  journal.append({ key, intent, state: "broadcast", txid });
+  return txid;
+}