@inixiative/signet 0.4.3 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@ A **Signet** is Kingdom's only grant for using an integration. It names the reso
 
 This package is the one implementation of that protocol, shared by Kingdom (which verifies) and Archive, Foundry and Oracle (which present):
 
-- `contracts`: the wire schemas: keys, lenses, proposals, pairing requests, delivered credentials, `describe` and `execute`.
+- `contracts`: the wire schemas: keys, lenses, proposals, pairing requests, delivered credentials, `describe` and `execute`, and the conversation frames.
 - `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
@@ -57,6 +57,35 @@ const signet = await SignetClient.fromFile(credentialFile);
 await signet.describe();
 ```
 
+## Agent conversations
+
+A conversation wraps a host Foundry's main thread (Kingdom `docs/AGENT-CONVERSATIONS.md`, Foundry `docs/reference/CONVERSATIONS.md`). A member is a Signet on the host Foundry's one `threads` resource; Kingdom admits each call and relays it over the host's Installation socket, and stores no conversation or message.
+
+- **Lens.** `signetLensSchema` is a union of strict shapes, `archiveLensSchema | threadsLensSchema`, because a resource grant names its resource by id with no kind. `resourceLensSchema(kind)` gives the shape a kind takes; Kingdom checks every grant with it against the kind it stores. A threads lens is `{ threads, view: 'own' | 'thread', delivery: 'note' | 'turn', outbound: 'review' | 'auto' }`, the terms defaulting to the narrowest value. `threads` is a selector, a union on `form`: v1 builds `{ form: 'ids', ids }` (1–100 thread ids); `withMember` and `tag` are named for standing Signets and fail to parse everywhere until a release adds them, so a new form never widens access silently. `narrowsSignetLens` is the rule for approving someone else's request: a subset of ids, `own` < `thread`, `note` < `turn`, `review` < `auto`.
+- **Join requests** may name a resource by kind: `requestSignet` takes `{ resourceKind: 'threads', operations, lens }`, and Kingdom resolves it before review.
+- **Per-entry reads.** `installationInquiries`, `installationSignets`, the socket snapshot and `describe` read each entry on its own. An entry this package can't read is dropped and listed in `dropped`, and the rest is kept. Inside a Signet, resources are read one by one: a resource with a lens this package can't read (a selector form from a newer Kingdom, a lens that doesn't fit its resource's kind) is dropped, and the Signet stays, so an installation never loses a held Signet, or mistakes a member for revoked, over one resource. The snapshot carries `hostedSignets` (members of this Foundry's conversations) and `hostedSignetRequests` (join requests aimed at its integrations); held Signets carry their `resources`.
+- **Host.** `InstallationSocket` takes `threads`, one handler per operation (`thread.read`, `thread.prompt`, `thread.floor`, `prompt.resolve`, `thread.subscribe`), answering `threadResult(...)` or `threadRefused(code)`. A frame with an unknown selector is refused `unknown_selector` before any handler runs. `thread.subscribe` answers with the member's view and the `journalSeq` it was taken at, and the subscription starts there: `appendThread(subscriptionId, entry)` holds entries pushed meanwhile and never sends one twice. Each append carries a dense per-subscription `seq` (a filtered view skips journal entries, so `journalSeq` can't reveal loss); an entry that can't be sent still spends its `seq`, so Kingdom sees the gap and the member resyncs. A subscription ends on `thread.unsubscribe`, when Kingdom stops re-asserting its lease (`thread.lease`; dropped 90 s after the last one, so one late 45 s sweep is survived), or when the socket drops.
+- **Member.** An outside agent holds its live views with `SignetSocket`: it authenticates as its Signet's presentation (`authenticateSignet`, a proof bound to `POST /api/v1/access/signetSocket` with `ath`), renews it before the five-minute token expires (`renewPresentation`), and opens one `accessThread` stream per thread: a snapshot, then appends, with Kingdom's `seq`/`resync` rules. Frames are handled in order, one open is in flight per stream, and Kingdom's close carries the reason: after a revision the stream reopens under the new lens, while the host is offline it retries with backoff, when the presentation lapsed the socket re-presents and reopens, and on revocation or expiry it ends (`onClosed`). Posts are separate `execute` calls (`thread.prompt`), each admitted and metered. A Foundry holding a conversation Signet opens the same streams over its Installation socket (`threadStreams`, `openThread`).
+
+```ts
+import { SignetClient, SignetSocket } from '@inixiative/signet';
+
+const signet = await SignetClient.fromFile(credentialFile);
+const socket = new SignetSocket({
+  client: signet,
+  onSnapshot: ({ threadId }, view) => show(threadId, view.entries),
+  onEntry: ({ threadId }, entry) => append(threadId, entry),
+  onClosed: ({ threadId }, reason) => console.log(`left ${threadId}: ${reason}`),
+});
+socket.open(threadId);
+socket.start();
+await signet.execute({
+  integrationId,
+  operation: 'thread.prompt',
+  input: { resourceId, threadId, postId: crypto.randomUUID(), text: 'The role you wanted opened' },
+});
+```
+
 Kingdom's OpenAPI spec (`/openapi/docs`) publishes each step's raw HTTP call and credentials.
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Present Kingdom Signets: the wire contracts, DPoP proofs, device pairing and a renewing client shared by Kingdom, Archive, Foundry and Oracle.",
   "type": "module",
   "main": "src/index.ts",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.93",
+    "@inixiative/config": "^0.5.115",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",

package/src/client.ts

@@ -7,10 +7,11 @@ import {
   accessTokenPattern,
   collectedSignetSchema,
   type InstallationKind,
-  installationInquiriesResponseSchema,
-  installationSignetsResponseSchema,
   nonceSchema,
   ownerRefSchema,
+  parseInstallationInquiries,
+  parseInstallationSignets,
+  parseSignetDescription,
   publicClientKeySchema,
   type RegistrationRequest,
   registerInstallationResponseSchema,
@@ -19,11 +20,11 @@ import {
   type SignetRequestResponse,
   setInstallationCredentialResponseSchema,
   signetCredentialsSchema,
-  signetDescriptionSchema,
   signetKeySchema,
   signetLifecycleSchema,
   signetProposalSchema,
   signetRequestResponseSchema,
+  signetSocketAction,
 } from './contracts';
 import { readPrivateJson, writePrivateJson } from './files';
 import { createSignetProof, keyThumbprint } from './proof';
@@ -224,7 +225,7 @@ async function keyPost<T>(
   keyFile: string,
   action: string,
   body: unknown,
-  schema: z.ZodType<T>,
+  schema: z.ZodType<T, unknown>,
   options: SignetRequestOptions = {},
   headers: Record<string, string> = {},
 ): Promise<T> {
@@ -274,13 +275,23 @@ export const requestRegistration = (
     options,
   );
 
-/** This installation's pending request and its inquiries. */
+/**
+ * This installation's pending request, its inquiries, and the join requests aimed at its
+ * integrations. Read per entry: an entry this package can't read is dropped and listed in `dropped`.
+ */
 export const installationInquiries = (
   url: string,
   keyFile: string,
   options: SignetRequestOptions = {},
 ) =>
-  keyPost(url, keyFile, 'installationInquiries', {}, installationInquiriesResponseSchema, options);
+  keyPost(
+    url,
+    keyFile,
+    'installationInquiries',
+    {},
+    z.unknown().transform((value) => parseInstallationInquiries(value)),
+    options,
+  );
 
 export const cancelInstallationInquiry = (
   url: string,
@@ -396,12 +407,23 @@ export const enrollSignet = async (
   signetId: enrollment.signetId,
 });
 
-/** The Signets held by this installation's integrations. */
+/**
+ * The Signets held by this installation's integrations, and those issued on them (`hostedSignets`).
+ * Read per entry: a Signet whose lens this package can't read is dropped and listed in `dropped`.
+ */
 export const installationSignets = (
   url: string,
   keyFile: string,
   options: SignetRequestOptions = {},
-) => keyPost(url, keyFile, 'installationSignets', {}, installationSignetsResponseSchema, options);
+) =>
+  keyPost(
+    url,
+    keyFile,
+    'installationSignets',
+    {},
+    z.unknown().transform((value) => parseInstallationSignets(value)),
+    options,
+  );
 
 /** Enroll this installation's key on a Signet one of its integrations holds. */
 export const enrollInstallationSignet = (
@@ -498,7 +520,7 @@ export class SignetClient {
   constructor(
     readonly url: string,
     private credentialFile: string,
-    private signetId: string,
+    readonly signetId: string,
   ) {
     this.url = kingdomUrl(url);
   }
@@ -588,11 +610,29 @@ export class SignetClient {
       { signal, timeoutMs: options.timeoutMs },
     );
   }
+  /** Read per entry: a resource whose lens this package can't read is dropped, listed in `dropped`. */
   async describe(options: SignetRequestOptions = {}) {
-    return signetDescriptionSchema.parse(
+    return parseSignetDescription(
       await this.post('describe', { signetId: this.signetId }, undefined, options),
     );
   }
+  /**
+   * The access token and a proof bound to the Signet socket, for `authenticateSignet` (or, with
+   * `renew`, a freshly renewed token for `renewPresentation`). Each proof spends one Kingdom nonce.
+   */
+  async socketPresentation(options: SignetRequestOptions & { renew?: boolean } = {}) {
+    const signal = requestSignal(options);
+    const credential = await this.credentials(options.renew ?? false, signal);
+    signal.throwIfAborted();
+    const proof = await signetProof(
+      this.url,
+      signetSocketAction,
+      credential.keyFile,
+      credential.accessToken,
+      { signal, timeoutMs: options.timeoutMs },
+    );
+    return { accessToken: credential.accessToken, proof, expiresAt: credential.expiresAt };
+  }
   /** Run one integration operation through the Signet; every call is a new request id. */
   async execute(
     request: Omit<AccessRequest, 'requestId' | 'signetId'>,