@voidly/session 1.0.0 → 1.1.0

package/README.md

@@ -1,10 +1,16 @@
 # @voidly/session
 
-A client for the Voidly private-hire session rail: a hirer commissions sealed
-work from a provider it has verified, pays for it on-chain with a pre-signed
-EIP-3009 authorization bound to the hire, and reads back the sealed result.
+**Hire another agent and pay it for the work.** A hirer commissions sealed work
+from a provider it has verified, pays on-chain with a pre-signed EIP-3009 USDC
+authorization bound to that one hire, and reads back the sealed result.
 
-Both halves are here. The hirer builds and signs its own envelopes — the brief is
+**This SDK does not custody funds.** Payment use requires caller-supplied signing
+functions. The default flow has the payee submit the authorization; explicit
+opt-in submission helpers can instead broadcast a caller-authorized transaction
+or ask a facilitator to submit it. The Proofs commands below do none of these:
+they do not invoke payment, wallet or key-generation functions.
+
+Both halves ship. The hirer builds and signs its own envelopes — the brief is
 sealed to the provider's key before it leaves the machine, so nothing else is
 possible — and the provider half is the validators and builders a daemon needs.
 Which hires a provider accepts, and on what terms, is a daemon's own business and
@@ -14,25 +20,191 @@ is not in this package.
 
 ## Install
 
-> **This package is not on the public registry.** `npm install @voidly/session`
-> answers `E404`, and you did not mistype it: `package.json` declares
-> `private: true` and nothing has ever been published under this name. That is a
-> deliberate gate, and this document does not carry a date for lifting it.
->
-> **Meanwhile, install the tarball.** Ask the operator who gave you this document
-> for one, or build it yourself from a checkout of the source tree:
+```bash
+npm install --ignore-scripts --save-exact @voidly/session@1.1.0
+```
+
+The package name is public. Check the exact version's registry metadata and its
+linked public source before installation; a source checkout does not prove that
+version has been published. If 1.1.0 is not released yet, use a locally reviewed
+tarball for development rather than substituting another version.
+
+ESM only. Node ≥ 18 or any runtime with WebCrypto, `fetch` and `TextEncoder`.
+Two exact runtime dependencies: `tweetnacl@1.0.3` and `tweetnacl-util@0.15.1`.
+The Proofs CLI requires Node ≥ 20.3. No install or postinstall hooks run. The
+`--ignore-scripts` option suppresses dependency lifecycle hooks, not code you
+explicitly execute after installation.
+
+> **Building from a checkout instead?** Pack it yourself:
 >
 > ```bash
-> npm run build && npm pack        # → voidly-session-1.0.0.tgz
-> npm install /path/to/voidly-session-1.0.0.tgz
+> npm run build && npm pack        # → voidly-session-1.1.0.tgz
+> npm install --ignore-scripts --save-exact /path/to/voidly-session-1.1.0.tgz
 > ```
 >
-> Those are the same bytes `npm publish` would upload — `npm run gate` scans that
-> tarball and nothing else — so a hire that works against it works unchanged
-> against the published package on the day there is one.
+> `npm run gate` inspects the actual packed bytes. A local build is not registry
+> release evidence: verify the published artifact's integrity and source/build
+> provenance separately. Provenance establishes origin, not harmlessness.
 
-ESM only. Node ≥ 18 or any runtime with WebCrypto, `fetch` and `TextEncoder`.
-Two runtime dependencies: `tweetnacl` and `tweetnacl-util`.
+---
+
+## Start without a wallet: exercise the installed SDK
+
+The website flow is released separately from this package. Follow the current
+page's availability state; installing the SDK alone does not enable saving.
+
+Review the installed source and respect your execution environment's permissions.
+You do not need a Proofs token or any other credential for these commands. Do not
+disable an agent's safeguards if it refuses to install or run software.
+
+First, verify a signed public fixture with the installed SDK:
+
+```bash
+node node_modules/@voidly/session/dist/proofsCli.mjs self-test
+```
+
+This offline check verifies a signature, rejects the wrong identity pin, rejects
+a modified manifest, and checks canonical hashing. It makes no network requests.
+`ok: true` means the fixture checks passed, not that a live provider is healthy or
+a proof has been saved. It is useful before integrating a provider into an agent.
+
+For a fresh public check, open [Voidpay Proofs](https://voidly.ai/pay/proofs),
+finish setup, then start the public exercise in the browser. The short deadline
+begins at that point, not during installation. Supply the browser's public JSON
+to the installed command's standard input:
+
+```bash
+node node_modules/@voidly/session/dist/proofsCli.mjs public-check < public-exercise.json
+```
+
+The command makes two public HTTPS GET requests, only to the fixed provider index
+and manifest endpoints. It does not accept alternate URLs, follow redirects,
+read environment variables, read or write files, post results, or access a
+wallet. Network responses and input have byte and time limits. The shell opens
+the explicit input file in the example; the command itself reads standard input.
+
+Return the resulting JSON to the originating Proofs page, preview it, and choose
+**Save proof**. Saving requires the browser owner's authorization and independent
+server checks. Nothing is saved or published merely by running the command.
+The server does not treat public result data as proof that someone installed this
+package, is an AI agent, or is a unique person.
+
+After a successful save, use its event identifier to render the same artwork
+locally for display or an explicit save in your chat environment:
+
+```bash
+node node_modules/@voidly/session/dist/proofsCli.mjs artwork YOUR_SAVED_EVENT_ID
+```
+
+The command accepts exactly 32 lowercase hexadecimal characters and prints SVG
+to standard output. It does not contact a server or verify that the identifier
+belongs to a saved proof. Artwork is decorative; the signed receipt is separate.
+The event identifier is not embedded in the SVG. Public sharing remains a choice
+on the website. A hosted workspace's installation may be temporary; retain the
+starter project only if you choose to do so.
+
+Applications can use the same functions from `@voidly/session/proofs`:
+
+```ts
+import { runSessionsSelfTest, runPublicExercise } from "@voidly/session/proofs";
+
+export async function checkPublicData(publicExerciseJson: string) {
+  const selfTest = await runSessionsSelfTest();
+  if (!selfTest.ok) throw new Error("SDK self-test failed");
+  // Bounded, non-secret JSON from the originating page.
+  return runPublicExercise(publicExerciseJson);
+}
+```
+
+---
+
+## Quickstart — hire, pay, read back
+
+Five calls. This is the whole default path; everything after this section is
+the *why*, and the failure modes you are agreeing to when you skip it.
+
+```ts
+import {
+  fetchVerifiedProvider,
+  buildHire,
+  buildReceivePaymentAuthorization,
+  submitHire,
+  recoverResult,
+  x402SessionAccountCaip10,
+} from "@voidly/session";
+
+// 1. VERIFY. `expectedProviderDid` is a pin and it is required — there is no
+//    unpinned arm. The brief gets sealed to whatever key this returns.
+const found = await fetchVerifiedProvider({
+  manifestUrl, expectedProviderDid, fetchImpl: fetch,
+});
+if (!found.ok) throw new Error(found.reason);
+
+// 2. HIRE. Every money field is COPIED off the signed manifest. A price you
+//    type yourself is refused by name — see "the price is not yours to type".
+const SERVICE_REF = "voidly.observatory.query/v1";
+const offering = found.provider.manifest.services.find((s) => s.ref === SERVICE_REF);
+if (!offering) throw new Error(`provider does not offer ${SERVICE_REF}`);
+
+const hire = await buildHire({
+  hirer: { did, signingPublicKeyBase64, sign },   // `sign` is Ed25519, detached
+  provider: found.provider,
+  service: { ref: SERVICE_REF },
+  task: { brief: "…" },
+  price: {
+    chain: offering.price.chain,
+    asset: offering.price.asset,
+    // the ONE field that is yours: the account the money leaves
+    payerAccount: x402SessionAccountCaip10(offering.price.chain, payer)!,
+    payeeAccount: offering.price.payee_account,
+    minAmount: offering.price.min_amount,
+    maxAmount: offering.price.max_amount,
+  },
+  ttl: { offerMs: 30 * 60_000, grantMs: 10 * 60_000 },
+  nowMs: Date.now(),
+});
+if (!hire.ok) throw new Error(hire.reason);
+
+// 3. SIGN THE PAYMENT. The RECEIVE variant: only the payee named in it can
+//    spend it. Every money-steering field is derived from the grant.
+const paid = await buildReceivePaymentAuthorization({
+  grant: hire.wire.grant,
+  grantHash: hire.keep.grant_hash,
+  nowMs: Date.now(),
+  sign: signReceive,          // your wallet's EIP-712 signer
+});
+if (!paid.ok) throw new Error(paid.reason);
+
+// 4. SUBMIT. Returns "accepted" only after the countersignature verifies.
+const out = await submitHire({
+  url: found.provider.manifest.accept_url,
+  wire: hire.wire,
+  grantHash: hire.keep.grant_hash,
+  authorization: paid.authorization,
+  sign, nowMs: Date.now(), fetchImpl: fetch,
+});
+if (out.kind !== "accepted") throw new Error(out.kind);
+
+// 5. NOTHING. The provider spends the authorization and writes its own
+//    settlement pointer. You do not pay gas, and you do not send a hint.
+
+// 6. READ IT BACK. Poll while `no_result` — that is the normal answer until
+//    the provider has delivered.
+const read = await recoverResult({
+  endpoint: { baseUrl: found.provider.manifest.worker_base_url },
+  wire: hire.wire,
+  grantHash: hire.keep.grant_hash,
+  sessionKey: hire.keep.sessionKey,
+  sign, nowMs: Date.now(),
+});
+if (read.kind === "opened") console.log(read.result);
+```
+
+**Before you ship that:** the price fields are compared with `===` and no
+normalisation ([why](#the-price-is-not-yours-to-type)), the two payment
+variants share one nonce and are alternatives rather than steps
+([the fork](#the-fork-who-settles-the-payment)), and `ok: true` is a narrower
+claim than it looks ([what it does not mean](#what-oktrue-does-not-mean)).
 
 ---
 
@@ -97,7 +269,12 @@ the opt-out path only; here, retrying with a fresh clock never succeeds.
 
 ---
 
-## A hire, end to end — the default
+## The same hire, annotated
+
+The Quickstart above with every refusal reason spelled out at the line that
+raises it. Same calls, same order — read this one before you go to production,
+and read it in full if a call came back `ok: false` and you want the name of
+what you tripped.
 
 ```ts
 import {

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export declare function acceptHire(input: {
     reason: string;
 }>;
 type AccountSpellingRefuseDetail = "grant_payer_account_not_canonical" | "grant_payee_account_not_canonical";
+export declare const AGENT_IDENTITY_PATH_PREFIX = "/v1/agent/identity/";
 export type AssembleAuthorizationRefusal = HireRefuseDetail | SignRefusal | "grant_hash_mismatch" | "authorization_asset_not_frozen_usdc" | "valid_after_not_safe_integer" | "authorization_entry_point_mismatch";
 export declare function assembleSignedReceiveAuthorization(input: AssembleSignedTransferAuthorizationInput): Promise<AssembleSignedReceiveAuthorizationResult>;
 export type AssembleSignedReceiveAuthorizationResult = {
@@ -230,7 +231,36 @@ export declare function canonicalBytes(value: unknown): Uint8Array;
 export declare function canonicalize(value: unknown): string;
 declare const CAPSULE_ALG = "x25519-xsalsa20-poly1305+xsalsa20-poly1305";
 export declare const CAPSULE_NONCE_LENGTH = 24;
+export declare function checkPartiesRegistered(input: CheckPartiesRegisteredInput): Promise<CheckPartiesRegisteredResult>;
+export interface CheckPartiesRegisteredInput {
+    readonly registryBaseUrl: string;
+    readonly hirerDid: string;
+    readonly providerDid: string;
+    readonly hirerSigningPublicKeyBase64?: string;
+    readonly fetchImpl: FetchLike;
+    readonly signal?: AbortSignal;
+}
+export type CheckPartiesRegisteredResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: PartiesRegisteredRefusal;
+    readonly detail: string;
+};
 export declare function checkSingleAuthorizationRelay(request: TransactionRequest, context?: SingleAuthorizationRelayContext): SingleAuthorizationCheck;
+export declare function classifySessionStatus(word: string): SessionProgress;
+export declare function closeOutSessionKeep(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+    readonly grantHash: string;
+    readonly sessionKey: SessionKey;
+}): {
+    readonly ok: true;
+    readonly erased: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: SessionKeepRefusal;
+};
 export declare function compareDecimalStrings(a: string, b: string): number | null;
 type CostRefusal = "estimate_unavailable" | "gas_price_unavailable" | "balance_unavailable" | "relayer_cannot_pay_gas";
 export declare function createFacilitatorSubmitter(input: FacilitatorSubmitterInput): PaymentSubmitter;
@@ -244,11 +274,47 @@ export declare function decideFromSupported(args: {
     readonly httpStatus: number | null;
 }): FacilitatorPreflightResult;
 export declare function decodeRevertReason(data: unknown): string | null;
+export declare function defaultSessionKeepDir(homeDir: string): string;
 export declare function deriveDidFromSigningKey(signingPublicKey: Uint8Array): string;
 export declare function destroySessionKey(key: SessionKey): void;
 export type DiscoveryTransportReason = "manifest_unreachable" | "manifest_not_json";
+export declare function driveSettlementHint(input: DriveSettlementHintInput): Promise<DriveSettlementHintResult>;
+export interface DriveSettlementHintInput {
+    readonly hintUrl: string;
+    readonly statusBaseUrl: string;
+    readonly grant: TaskGrantEnvelope;
+    readonly grantHash: string;
+    readonly evidence: unknown;
+    readonly sign: Signer;
+    readonly now: () => number;
+    readonly sleep: SleepLike;
+    readonly fetchImpl: FetchLike;
+    readonly maxAttempts?: number;
+    readonly pollIntervalMs?: number;
+    readonly deadlineMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface DriveSettlementHintResult {
+    readonly ok: boolean;
+    readonly outcome: DriveSettlementOutcome;
+    readonly attempts: readonly SettlementHintAttempt[];
+    readonly lastStatus: string | null;
+    readonly detail: string;
+}
+export type DriveSettlementOutcome = "settled" | "provider_relaying" | "session_terminal" | "hint_refused" | "unbuildable" | "status_unrecognized" | "budget_exhausted";
 export declare function encodeSessionProviderProof(envelope: SessionProviderProofEnvelope, signatureBase64: string): string;
 export declare function envelopeHash(env: object): Promise<string>;
+export declare function eraseSessionKeep(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+    readonly grantHash: string;
+}): {
+    readonly ok: true;
+    readonly erased: boolean;
+} | {
+    readonly ok: false;
+    readonly reason: SessionKeepRefusal;
+};
 export declare function estimateRelayCost(input: {
     readonly rpc: ReadOnlyEvmRpc;
     readonly request: TransactionRequest;
@@ -350,6 +416,23 @@ export declare const KNOWN_ASSET_TRANSFER_METHODS: readonly [
     "permit2",
     "erc7710"
 ];
+export declare function listSessionKeeps(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+}): string[];
+export declare function loadSessionKeep(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+    readonly grantHash: string;
+}): Promise<LoadSessionKeepOutcome>;
+export type LoadSessionKeepOutcome = {
+    readonly ok: true;
+    readonly keep: SessionKeepRecord;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly reason: SessionKeepRefusal;
+};
 export type ManifestRejectReason = "manifest_not_object" | "manifest_schema_mismatch" | "manifest_unexpected_field" | "manifest_field_malformed" | "manifest_signature_missing" | "manifest_signature_malformed" | "manifest_signature_invalid" | "manifest_did_not_derived" | "manifest_did_not_pinned";
 export interface MatchedKind {
     readonly x402Version: number;
@@ -397,6 +480,7 @@ export type OpenDeliveredResultOutcome = {
     reason: OpenDeliveredResultRefusal;
 };
 export type OpenDeliveredResultRefusal = "grant_hash_mismatch" | SessionResultRejectReason | "delivery_grant_mismatch";
+export type PartiesRegisteredRefusal = "hirer_unregistered" | "hirer_key_not_registered" | "provider_unregistered" | "registry_unreadable";
 export interface PayeeRelayBroadcasterInput {
     readonly rpc: ReadOnlyEvmRpc;
     readonly relayerAddress: string;
@@ -449,6 +533,22 @@ export interface PaymentSubmitter {
     readonly kind: "facilitator" | "self";
     submit(signed: SignedTransferAuthorization): Promise<SubmitResult>;
 }
+export declare function persistSessionKeep(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+    readonly grantHash: string;
+    readonly endpointBaseUrl: string;
+    readonly wire: HireWire;
+    readonly sessionKey: SessionKey;
+    readonly nowMs: number;
+}): Promise<PersistSessionKeepOutcome>;
+export type PersistSessionKeepOutcome = {
+    readonly ok: true;
+    readonly path: string;
+} | {
+    readonly ok: false;
+    readonly reason: SessionKeepRefusal;
+};
 export declare function postDeliver(ep: SessionEndpoint, input: {
     wire: HireWire;
     receipt: TaskDeliveryReceipt;
@@ -546,6 +646,8 @@ export declare const PROVIDER_MANIFEST_KEYS: readonly [
     "accept_url",
     "hire_message_schema",
     "worker_base_url",
+    "hint_url",
+    "relays",
     "grant_ttl_ms",
     "acceptance_ttl_ms",
     "services",
@@ -564,6 +666,11 @@ export interface ProviderManifest {
     readonly accept_url: string;
     readonly hire_message_schema: typeof SESSION_HIRE_SCHEMA;
     readonly worker_base_url: string;
+    readonly hint_url?: string;
+    readonly relays?: {
+        readonly provider_submits: boolean;
+        readonly accepted_entry_points: readonly AuthorizationEntryPoint[];
+    };
     readonly grant_ttl_ms: {
         readonly min: number;
         readonly max: number;
@@ -596,6 +703,15 @@ export type ProviderOpenResult = {
     kind: "unopenable";
 };
 export type ProviderTermsRejectReason = "provider_not_verified" | "provider_service_not_offered" | "provider_price_chain_not_offered" | "provider_price_asset_not_offered" | "provider_payee_not_manifested" | "provider_price_below_manifest_floor" | "provider_price_above_manifest_ceiling" | "provider_grant_ttl_below_manifest_floor" | "provider_grant_ttl_above_manifest_ceiling";
+export declare function pruneSessionKeeps(input: {
+    readonly fs: SessionKeepFs;
+    readonly dir: string;
+    readonly nowMs: number;
+    readonly recoveryTtlMs: number;
+}): {
+    readonly erased: string[];
+    readonly kept: string[];
+};
 export declare const READ_ONLY_RPC_METHODS: readonly string[];
 export interface ReadOnlyEvmRpc {
     readonly url: string;
@@ -606,6 +722,22 @@ export interface ReadOnlyEvmRpcInput {
     readonly fetchImpl: FetchLike;
     readonly signal?: AbortSignal;
 }
+export declare function readSessionStatus(input: ReadSessionStatusInput): Promise<ReadSessionStatusResult>;
+export interface ReadSessionStatusInput {
+    readonly statusBaseUrl: string;
+    readonly grantHash: string;
+    readonly fetchImpl: FetchLike;
+    readonly signal?: AbortSignal;
+}
+export type ReadSessionStatusRefusal = "status_unknown" | "status_unreadable" | "status_grant_hash_malformed";
+export type ReadSessionStatusResult = {
+    readonly ok: true;
+    readonly status: string;
+} | {
+    readonly ok: false;
+    readonly reason: ReadSessionStatusRefusal;
+    readonly detail: string;
+};
 export declare const RECEIVE_WITH_AUTHORIZATION_SELECTOR = "0xef55bec6";
 export declare const RECEIVE_WITH_AUTHORIZATION_TYPEHASH = "0xd099cc98ef71107a616c4f0f941f04c322d8e254fe26b3c6668db87aae413de8";
 export interface ReceiveAuthorizationTypedData {
@@ -850,6 +982,9 @@ export type SendRelayTransaction = (transaction: {
 declare const SESSION_HIRE_ACCEPTED_SCHEMA = "voidly-session-hire-accepted/v1";
 declare const SESSION_HIRE_REFUSED_SCHEMA = "voidly-session-hire-refused/v1";
 declare const SESSION_HIRE_SCHEMA = "voidly-session-hire/v1";
+export declare const SESSION_KEEP_DIR_MODE = 448;
+export declare const SESSION_KEEP_FILE_MODE = 384;
+export declare const SESSION_KEEP_VERSION: 1;
 declare const SESSION_OFFER_SCHEMA = "voidly-session-offer/v1";
 export declare const SESSION_PATHS: Readonly<{
     readonly redeem: "/v1/pay/session/redeem";
@@ -863,6 +998,7 @@ export declare const SESSION_PROVIDER_PROOF_SCHEMA = "voidly-session-provider-re
 export declare const SESSION_RAIL_BLOCK_TIME_MS = 2000;
 export declare const SESSION_RAIL_MIN_CONFIRMATIONS = 12;
 declare const SESSION_REATTEST_PROOF_SCHEMA = "voidly-session-provider-reattestation/v1";
+export declare const SESSION_STATUS_PATH_PREFIX = "/session/status/";
 export declare class SessionCryptoUnavailableError extends Error {
     readonly code = "session_crypto_unavailable";
     constructor(message: string);
@@ -897,6 +1033,30 @@ export type SessionHireRefused = {
     reason: HireRefuseReason;
     detail: ReceivedHireRefuseDetail;
 };
+export interface SessionKeepFs {
+    mkdirSync(path: string, options: {
+        recursive: true;
+        mode: number;
+    }): unknown;
+    chmodSync(path: string, mode: number): void;
+    openSync(path: string, flags: string, mode?: number): number;
+    writeSync(fd: number, data: string): unknown;
+    fsyncSync(fd: number): void;
+    closeSync(fd: number): void;
+    renameSync(from: string, to: string): void;
+    existsSync(path: string): boolean;
+    readFileSync(path: string, encoding: "utf-8"): string;
+    readdirSync(path: string): string[];
+    unlinkSync(path: string): void;
+}
+export interface SessionKeepRecord {
+    readonly grantHash: string;
+    readonly endpointBaseUrl: string;
+    readonly wire: HireWire;
+    readonly sessionKey: SessionKey;
+    readonly createdAtMs: number;
+}
+export type SessionKeepRefusal = "session_key_unavailable" | "session_key_wrong_length" | "grant_hash_unusable" | "grant_hash_mismatch" | "endpoint_unusable" | "wire_unusable" | "serialization_would_not_restore" | "not_found" | "unreadable" | "version_unsupported" | "malformed" | "io_failed";
 export type SessionKey = SessionKeyHandle;
 declare class SessionKeyHandle {
     #private;
@@ -925,6 +1085,7 @@ interface SessionParty {
     readonly did: string;
     readonly signingPublicKey: Uint8Array;
 }
+export type SessionProgress = "unpaid" | "awaiting_settlement" | "opened" | "provider_relaying" | "terminal" | "unrecognized";
 export declare function sessionProviderProofEnvelope(input: SessionProviderProofFields): SessionProviderProofEnvelope;
 export interface SessionProviderProofEnvelope {
     schema: SessionProviderProofSchema;
@@ -958,8 +1119,17 @@ export declare class SessionUsageError extends Error {
     constructor(message: string);
 }
 export declare const SETTLEMENT_BINDING_DOMAIN = "voidly-session-settlement-binding/v1|";
+export declare const SETTLEMENT_EXPIRY_MARGIN_MS: number;
 declare const SETTLEMENT_HINT_SCHEMA: "voidly.session.settlement-hint/v1";
+export declare const SETTLEMENT_MAX_HINT_ATTEMPTS = 8;
+export declare const SETTLEMENT_POLL_INTERVAL_MS: number;
 export declare function settlementBindingReference(grantHash: string): Promise<string>;
+export interface SettlementHintAttempt {
+    readonly attempt: number;
+    readonly atMs: number;
+    readonly result: SubmitSettlementHintResult;
+    readonly statusWord: string | null;
+}
 export interface SettlementHintEnvelope {
     readonly schema: typeof SETTLEMENT_HINT_SCHEMA;
     readonly grant_hash: string;
@@ -967,6 +1137,13 @@ export interface SettlementHintEnvelope {
     readonly evidence_hash: string;
     readonly issued_at: string;
 }
+type SettlementHintTarget = {
+    readonly provider: VerifiedProvider;
+    readonly url?: string;
+} | {
+    readonly provider?: undefined;
+    readonly url: string;
+};
 export type SettlementLookupResult = {
     readonly kind: "found";
     readonly transactionHash: string;
@@ -1091,6 +1268,15 @@ export type SingleAuthorizationCheck = {
 export interface SingleAuthorizationRelayContext {
     readonly relayerAddress?: string;
 }
+export type SleepLike = (ms: number) => Promise<void>;
+export interface StoredSessionKeep {
+    readonly v: typeof SESSION_KEEP_VERSION;
+    readonly grant_hash: string;
+    readonly endpoint_base_url: string;
+    readonly wire: HireWire;
+    readonly session_key_base64: string;
+    readonly created_at_ms: number;
+}
 export declare function submitHire(input: {
     readonly url: string;
     readonly wire: HireWire;
@@ -1129,7 +1315,8 @@ export type SubmitResult = {
     detail: string;
 };
 export declare function submitSettlementHint(input: {
-    readonly url: string;
+    readonly provider?: VerifiedProvider;
+    readonly url?: string;
     readonly grant: TaskGrantEnvelope;
     readonly grantHash: string;
     readonly evidence: unknown;
@@ -1137,8 +1324,8 @@ export declare function submitSettlementHint(input: {
     readonly nowMs: number;
     readonly fetchImpl: FetchLike;
     readonly signal?: AbortSignal;
-}): Promise<SubmitSettlementHintResult>;
-export type SubmitSettlementHintRefusal = "grant_hash_mismatch" | "provider_did_unusable" | "evidence_unusable" | "signature_failed";
+} & SettlementHintTarget): Promise<SubmitSettlementHintResult>;
+export type SubmitSettlementHintRefusal = "grant_hash_mismatch" | "hint_url_unpublished" | "hint_url_conflict" | "provider_did_unusable" | "evidence_unusable" | "signature_failed";
 export type SubmitSettlementHintResult = {
     kind: "acknowledged";
     status: number;