@adonis-agora/agent 0.93.0 → 0.95.0

package/dist/src/poppy/auth.d.ts

@@ -2,32 +2,35 @@ import type { Actor } from '../types.js';
 /**
  * Who a Poppy request comes from: a Personal Agent (`clientId`) acting for one of its Users
  * (`userId`, the pairwise User ID — not an account) in one Session. `signedIn`, with the app
- * account (`accountId`) and `scopes`, once the User signed in here (§4.4); a signed-out token has
- * neither. The shape `@adonis-agora/authkit-server` answers.
+ * account (`accountId`) and `scopes`, on a request that carries an access token (§5.4); a signed-out
+ * request has neither. The shape `@adonis-agora/authkit-server` answers.
  */
 export interface PoppyPrincipal {
     /** The opaque, stable id the Personal Agent gave this User here. */
     userId: string;
-    /** The app account, when the Session is signed in; `null` signed out. */
+    /** Which of the User's agents this Session is for (§5.1), if the Personal Agent says. */
+    agentId?: string | null;
+    /** The app account, when the request carries an access token; `null` signed out. */
     accountId: string | null;
     /** The Personal Agent's `client_id` (its metadata document URL). */
     clientId: string;
-    /** The token's account scopes (`poppy:read`, `poppy:write`, custom). Empty signed out. */
+    /** The access token's scopes. Empty signed out. */
     scopes: string[];
     sessionId: string;
     signedIn: boolean;
     /** The `resource` the token was issued for (RFC 8707), or `null`. */
     resource?: string | null;
-    tokenType?: 'DPoP' | 'Bearer';
+    /** The access token's scheme; `null` signed out. */
+    tokenType?: 'DPoP' | 'Bearer' | null;
     /** What the app's `personalAgents.poppy.toActor` answered, when it has one. */
     actor?: Actor;
 }
-/** The request a resolver verifies — the Session Token and its DPoP proof are in `headers`. */
+/** The request a resolver verifies — the `Poppy-Session` JWT and any access token are in `headers`. */
 export interface PoppyAuthRequest {
     method: string;
-    /** The full PUBLIC request URL (the DPoP `htu` is checked against it; the query is ignored). */
+    /** The full PUBLIC request URL (the Session JWT's `htu` is checked against it; the query is ignored). */
     url: string;
-    /** The request's headers as received (lower-cased names) — `authorization` and `dpop` included. */
+    /** The request's headers as received (lower-cased names) — `poppy-session`, `authorization` and `dpop` included. */
     headers: Record<string, string | string[] | undefined>;
 }
 /**
@@ -42,14 +45,15 @@ export interface PoppyAuthOptions {
 }
 export type PoppyAuthFailure = {
     ok: false;
-    status: 400 | 401 | 403;
-    error: 'invalid_token' | 'sign_in_required' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce' | (string & {});
+    status: 400 | 401 | 403 | 429;
+    /** `null`: a challenge without a code (§8, the request needs the account) or a rate limit (§5.6). */
+    error: 'invalid_session' | 'invalid_token' | 'insufficient_scope' | 'invalid_dpop_proof' | 'use_dpop_nonce' | (string & {}) | null;
     scope?: string;
-    /** The challenge to answer with, verbatim. */
-    wwwAuthenticate: string;
-    /** For logs and the body's `error_description` — never the token. */
+    /** The challenge to answer with, verbatim; `null` for `invalid_session` and rate limits. */
+    wwwAuthenticate: string | null;
+    /** For logs and `invalid_session`'s `error_description` — never a token. */
     description?: string;
-    /** Extra headers to answer with (`DPoP-Nonce`). */
+    /** Extra headers to answer with (`DPoP-Nonce`, `Retry-After`). */
     headers?: Record<string, string>;
 };
 export type PoppyAuthResult = {
@@ -57,10 +61,10 @@ export type PoppyAuthResult = {
     principal: PoppyPrincipal;
 } | PoppyAuthFailure;
 /**
- * Verifies a request's Session Token. `@adonis-agora/authkit-server` installs one in the global
+ * Verifies a request's Session header and any access token. `@adonis-agora/authkit-server` installs one in the global
  * slot {@link POPPY_AUTHENTICATE_SLOT}; an app can pass its own (`definePoppyConfig({ authenticate })`).
  *
- * @experimental Tracks Personal Agent Protocol Draft 0.1 (https://personalagentprotocol.org/docs/spec),
+ * @experimental Tracks Personal Agent Protocol Draft 0.3 (https://personalagentprotocol.org/docs/spec),
  * a spec still in development: this API WILL change as the spec evolves — possibly in breaking
  * ways, outside semver majors while it is a draft.
  */

package/dist/src/poppy/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/poppy/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC9B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,+FAA+F;AAC/F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,gGAAgG;IAChG,GAAG,EAAE,MAAM,CAAC;IACZ,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACxB,KAAK,EACD,eAAe,GACf,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,cAAc,CAAA;CAAE,GAAG,gBAAgB,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B;;;GAGG;AACH,eAAO,MAAM,uBAAuB,eAAiD,CAAC;AAEtF,sGAAsG;AACtG,wBAAgB,uBAAuB,IAAI,iBAAiB,GAAG,SAAS,CAGvE;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAGtD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/poppy/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oFAAoF;IACpF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACrC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,uGAAuG;AACvG,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,GAAG,EAAE,MAAM,CAAC;IACZ,oHAAoH;IACpH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IAC9B,qGAAqG;IACrG,KAAK,EACD,iBAAiB,GACjB,eAAe,GACf,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,CAAC,MAAM,GAAG,EAAE,CAAC,GACb,IAAI,CAAC;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,cAAc,CAAA;CAAE,GAAG,gBAAgB,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAC9B,OAAO,EAAE,gBAAgB,EACzB,OAAO,CAAC,EAAE,gBAAgB,KACvB,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B;;;GAGG;AACH,eAAO,MAAM,uBAAuB,eAAiD,CAAC;AAEtF,sGAAsG;AACtG,wBAAgB,uBAAuB,IAAI,iBAAiB,GAAG,SAAS,CAGvE;AAED,+FAA+F;AAC/F,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAGtD"}

package/dist/src/poppy/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/poppy/auth.ts"],"names":[],"mappings":"AAgFA;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAEtF,sGAAsG;AACtG,MAAM,UAAU,uBAAuB;IACrC,MAAM,KAAK,GAAI,UAAsC,CAAC,uBAAuB,CAAC,CAAC;IAC/E,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAA2B,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAI,UAAsC,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC;IAChG,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/poppy/auth.ts"],"names":[],"mappings":"AAqFA;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;AAEtF,sGAAsG;AACtG,MAAM,UAAU,uBAAuB;IACrC,MAAM,KAAK,GAAI,UAAsC,CAAC,uBAAuB,CAAC,CAAC;IAC/E,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAA2B,CAAC,CAAC,CAAC,SAAS,CAAC;AAChF,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAI,UAAsC,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC;IAChG,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvE,CAAC"}

package/dist/src/poppy/conversations.d.ts

@@ -1,7 +1,7 @@
 import { type A2aActionPolicy, type A2aTurnOutcome, type A2aTurnService } from '../a2a/turn.js';
 import type { Actor } from '../types.js';
 import type { PoppyPrincipal } from './auth.js';
-import { type PoppyEvent, type PoppyEventMessage, type PoppyResponder, type PoppySendBody, type PoppySender, type PoppyStatus } from './protocol.js';
+import { type PoppyAuthor, type PoppyEvent, type PoppyEventMessage, type PoppyResponder, type PoppySendBody, type PoppyStatus } from './protocol.js';
 import { type PoppyConversationRecord, type PoppyStore } from './store.js';
 /** What the hooks are told about a conversation. */
 export interface PoppyHookContext {
@@ -15,13 +15,13 @@ export interface PoppyHookContext {
  *  - `'queued'` — someone will join: call {@link PoppyConversations.humanJoined} when they do, or
  *    {@link PoppyConversations.handoffUnavailable} if nobody can.
  *  - `'joined'` — a person took it now.
- *  - `{ unavailable }` — nobody can; the text is what the Company Agent says (§7.9).
+ *  - `{ unavailable }` — nobody can; the text is what the Company Agent says (§8.9).
  */
 export type PoppyHandoffDecision = 'queued' | 'joined' | {
     unavailable: string;
 };
 /**
- * How the app brings a person in (§7.9). Without these, a handoff is answered by the Company Agent
+ * How the app brings a person in (§8.9). Without these, a handoff is answered by the Company Agent
  * saying no one is available — the conversation stays with the agent.
  */
 export interface PoppyHandoffHooks {
@@ -36,10 +36,10 @@ export interface PoppyHandoffHooks {
     message?(ctx: PoppyHookContext & {
         message: PoppyEventMessage;
     }): void | Promise<void>;
-    /** The conversation closed while a person was handling it or being found (§7.12). */
+    /** The conversation closed while a person was handling it or being found (§8.12). */
     cancel?(ctx: PoppyHookContext): void | Promise<void>;
 }
-/** Notified when the Personal Agent opens or closes a Direct Conversation (§7.10). */
+/** Notified when the Personal Agent opens or closes a Direct Conversation (§8.10). */
 export interface PoppyDirectHooks {
     opened?(ctx: PoppyHookContext & {
         parentId: string;
@@ -50,11 +50,11 @@ export interface PoppyDirectHooks {
 }
 /** What the Company Agent says on its own. */
 export interface PoppyTexts {
-    /** A handoff with no one to take it (§7.9). */
+    /** A handoff with no one to take it (§8.9). */
     handoffUnavailable: string;
     /** A turn that failed before saying anything. */
     failed: string;
-    /** Asked in a Direct Conversation alongside an `authorization` event (§7.11 SHOULD). */
+    /** Asked in a Direct Conversation alongside an `authorization` event (§8.11 SHOULD). */
     signIn: string;
     /** An action that ran — `{title}` is the app's confirmation title (default {@link formatPoppyAction}). */
     actionSucceeded: string;
@@ -67,7 +67,7 @@ export declare const DEFAULT_POPPY_TEXTS: PoppyTexts;
 /** An action of the turn, as the reply's `data.actions` carries it. */
 export type PoppyActionOutcome = A2aTurnOutcome;
 /**
- * Words an action for the reply's text (§7: the message must make sense without `data`). Return
+ * Words an action for the reply's text (§8: the message must make sense without `data`). Return
  * `null` to leave it out. Default {@link formatPoppyAction}.
  */
 export type PoppyActionFormatter = (action: PoppyActionOutcome, texts: PoppyTexts) => string | null | undefined;
@@ -106,7 +106,7 @@ export interface PoppyConversationsOptions {
     /** Logs what fails outside a request (a turn, a hook). */
     onError?: (error: unknown, context: string) => void;
 }
-/** What a read answers (§7.5). */
+/** What a read answers (§8.5). */
 export interface PoppyReadResult {
     conversation_id: string;
     events: PoppyEvent[];
@@ -115,7 +115,7 @@ export interface PoppyReadResult {
     status: PoppyStatus;
     responder: PoppyResponder;
 }
-/** What a stream yields: a stored event, or a provisional piece of text (§7.6). */
+/** What a stream yields: a stored event, or a provisional piece of text (§8.6). */
 export type PoppyStreamItem = {
     kind: 'event';
     event: PoppyEvent;
@@ -130,7 +130,7 @@ export type PoppyStreamItem = {
 /** The actor of a principal the resolver gave none: stable per (Personal Agent, its User). */
 export declare function poppyActorId(clientId: string, userId: string): string;
 /**
- * Poppy conversations (§7) over the agent runtime: the state machine, the event log and the turns.
+ * Poppy conversations (§8) over the agent runtime: the state machine, the event log and the turns.
  * HTTP-free — `createPoppyHandler` puts the protocol's requests on it, and the app drives the
  * Company side through it (a person joining, their messages, `user_requested`).
  *
@@ -140,7 +140,7 @@ export declare function poppyActorId(clientId: string, userId: string): string;
  * then appends the reply as a `message` event. A replica that finds a conversation `working` with
  * no pump picks it up, so a reply survives the process that started it.
  *
- * @experimental Tracks Personal Agent Protocol Draft 0.1 (https://personalagentprotocol.org/docs/spec),
+ * @experimental Tracks Personal Agent Protocol Draft 0.3 (https://personalagentprotocol.org/docs/spec),
  * a spec still in development: this API WILL change as the spec evolves — possibly in breaking
  * ways, outside semver majors while it is a draft.
  */
@@ -163,17 +163,17 @@ export declare class PoppyConversations {
         body: Record<string, unknown>;
         conversationId: string;
     }>;
-    /** `POST {endpoint}/{id}/messages` — another message (§7.3). */
+    /** `POST {endpoint}/{id}/messages` — another message (§8.3). */
     send(principal: PoppyPrincipal, conversationId: string, body: PoppySendBody): Promise<{
         status: number;
         body: Record<string, unknown>;
     }>;
-    /** `GET {endpoint}/{id}/events` without streaming — read (and wait for) events (§7.5). */
+    /** `GET {endpoint}/{id}/events` without streaming — read (and wait for) events (§8.5). */
     read(principal: PoppyPrincipal, conversationId: string, options: {
         cursor?: string;
         waitMs?: number;
     }): Promise<PoppyReadResult>;
-    /** A read of a conversation already checked — also what a POST with `wait` answers (§7.3). */
+    /** A read of a conversation already checked — also what a POST with `wait` answers (§8.3). */
     readOwned(conversation: PoppyConversationRecord, options: {
         cursor?: string;
         waitMs?: number;
@@ -181,17 +181,17 @@ export declare class PoppyConversations {
     /** Check a conversation is the principal's, for a caller that reads it afterwards. */
     owned(principal: PoppyPrincipal, conversationId: string): Promise<PoppyConversationRecord>;
     /**
-     * `GET {endpoint}/{id}/events` as SSE (§7.6): the events after `cursor`, then new ones as they
+     * `GET {endpoint}/{id}/events` as SSE (§8.6): the events after `cursor`, then new ones as they
      * come, with `text-delta` pieces of a reply being written in this process. Ends when `signal`
      * aborts, or once the conversation is closed and every event was sent.
      */
     stream(conversation: PoppyConversationRecord, cursor: string | undefined, signal: AbortSignal): AsyncGenerator<PoppyStreamItem>;
-    /** `POST {endpoint}/{id}/handoff` — ask for a person at the Company (§7.9). */
+    /** `POST {endpoint}/{id}/handoff` — ask for a person at the Company (§8.9). */
     requestHandoff(principal: PoppyPrincipal, conversationId: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
     }>;
-    /** `POST {endpoint}/{id}/close` — close the conversation (§7.12). */
+    /** `POST {endpoint}/{id}/close` — close the conversation (§8.12). */
     closeByAgent(principal: PoppyPrincipal, conversationId: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
@@ -199,19 +199,19 @@ export declare class PoppyConversations {
     /** Look a conversation up — for the app's own routing (a support tool, an admin page). */
     get(conversationId: string): Promise<PoppyConversationRecord | null>;
     /**
-     * Close a conversation (§7.12): its open Direct Conversation first, a pending handoff is
+     * Close a conversation (§8.12): its open Direct Conversation first, a pending handoff is
      * cancelled, and a `closed` state event added. Nothing it started is undone. Idempotent.
      */
     close(conversationId: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
     }>;
-    /** The Company Agent hands off to a person on its own (§7.9) — e.g. from one of your tools. */
+    /** The Company Agent hands off to a person on its own (§8.9) — e.g. from one of your tools. */
     handoff(conversationId: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
     }>;
-    /** A person at the Company joined: `responder` becomes `human` (§7.7). */
+    /** A person at the Company joined: `responder` becomes `human` (§8.7). */
     humanJoined(conversationId: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
@@ -223,23 +223,23 @@ export declare class PoppyConversations {
     }>;
     /**
      * No one could take a queued handoff: the Company Agent says why, and the conversation goes back
-     * to `idle` with the agent (§7.9).
+     * to `idle` with the agent (§8.9).
      */
     handoffUnavailable(conversationId: string, reason?: string): Promise<{
         status: PoppyStatus;
         responder: PoppyResponder;
     }>;
     /**
-     * Add a Company message — a person's (`sender: 'human'`, while they handle the conversation) or
+     * Add a Company message — a person's (`author.type: 'human'`, while they handle the conversation) or
      * an automated one. Answers the message's id.
      */
     postMessage(conversationId: string, message: {
         text?: string;
         data?: Record<string, unknown>;
-        sender: PoppySender;
+        author: PoppyAuthor;
     }): Promise<string>;
     /**
-     * Ask to talk with the User directly (§7.10): a `user_requested` event. Only the Personal Agent
+     * Ask to talk with the User directly (§8.10): a `user_requested` event. Only the Personal Agent
      * opens the Direct Conversation, once the User agrees.
      */
     requestUser(conversationId: string, reason: string): Promise<void>;

package/dist/src/poppy/conversations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../../src/poppy/conversations.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conversations.d.ts","sourceRoot":"","sources":["../../../src/poppy/conversations.ts"],"names":[],"mappings":"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"}

package/dist/src/poppy/conversations.js

@@ -36,7 +36,7 @@ const PRUNE_EVERY_MS = 60_000;
 export function poppyActorId(clientId, userId) {
     return `poppy:${createHash('sha256').update(`${clientId}\n${userId}`).digest('hex').slice(0, 40)}`;
 }
-/** The idempotency owner of §7.3: message ids are unique per User of a Personal Agent. */
+/** The idempotency owner of §8.3: message ids are unique per User of a Personal Agent. */
 function ownerKey(principal) {
     return createHash('sha256').update(`${principal.clientId}\n${principal.userId}`).digest('hex');
 }
@@ -57,7 +57,7 @@ function turnText(messages) {
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 /**
- * Poppy conversations (§7) over the agent runtime: the state machine, the event log and the turns.
+ * Poppy conversations (§8) over the agent runtime: the state machine, the event log and the turns.
  * HTTP-free — `createPoppyHandler` puts the protocol's requests on it, and the app drives the
  * Company side through it (a person joining, their messages, `user_requested`).
  *
@@ -67,7 +67,7 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * then appends the reply as a `message` event. A replica that finds a conversation `working` with
  * no pump picks it up, so a reply survives the process that started it.
  *
- * @experimental Tracks Personal Agent Protocol Draft 0.1 (https://personalagentprotocol.org/docs/spec),
+ * @experimental Tracks Personal Agent Protocol Draft 0.3 (https://personalagentprotocol.org/docs/spec),
  * a spec still in development: this API WILL change as the spec evolves — possibly in breaking
  * ways, outside semver majors while it is a draft.
  */
@@ -110,7 +110,7 @@ export class PoppyConversations {
             roles: [...new Set([...(actor.roles ?? []), PERSONAL_AGENT_ROLE, ...scopes.map(scopeRole)])],
         };
     }
-    /** The account a signed-in principal is — what a conversation binds to once used (§7.2). */
+    /** The account a signed-in principal is — what a conversation binds to once used (§8.2). */
     async #accountOf(principal) {
         if (!principal.signedIn)
             return null;
@@ -124,9 +124,9 @@ export class PoppyConversations {
         };
     }
     /**
-     * The conversation, when `principal` may use it (§7.2): the same Personal Agent and User — and
+     * The conversation, when `principal` may use it (§8.2): the same Personal Agent and User — and
      * once it used an account, a token signed in to that account. Anything else is indistinguishable
-     * from no conversation, except a signed-out token of its own User: `sign_in_required` (§7.11).
+     * from no conversation, except a signed-out request of its own User: a challenge (§8.11).
      */
     async #owned(principal, id) {
         const conversation = await this.options.store.getConversation(id);
@@ -141,7 +141,7 @@ export class PoppyConversations {
                 return conversation;
             }
             if (conversation.userId === principal.userId) {
-                throw new PoppyError('sign_in_required', 'This conversation used your account: sign in');
+                throw new PoppyError('account_required', 'This conversation used your account: sign in');
             }
             throw new PoppyError('conversation_not_found');
         }
@@ -169,7 +169,7 @@ export class PoppyConversations {
             this.#bus.emit(`event:${conversationId}`, event);
         return event;
     }
-    /** Change status and/or responder; every change is a `state` event (§7.7). */
+    /** Change status and/or responder; every change is a `state` event (§8.7). */
     async #setState(conversation, next, extra = {}) {
         const status = next.status ?? conversation.status;
         const responder = next.responder ?? conversation.responder;
@@ -180,11 +180,11 @@ export class PoppyConversations {
             await this.#append(conversation.id, { type: 'state', status, responder });
         return updated;
     }
-    #companyMessage(text, data, sender, id = newPoppyId('msg')) {
+    #companyMessage(text, data, author, id = newPoppyId('msg')) {
         return {
             id,
             role: 'company',
-            sender,
+            author,
             ...(text !== undefined && text !== '' ? { text } : {}),
             ...(data !== undefined ? { data } : {}),
         };
@@ -198,7 +198,7 @@ export class PoppyConversations {
         let parent = null;
         if (body.parentConversationId !== undefined) {
             parent = await this.#owned(principal, body.parentConversationId);
-            // A Direct Conversation is not a parent (§7.10): as a parent, it does not exist.
+            // A Direct Conversation is not a parent (§8.10): as a parent, it does not exist.
             if (parent.parentId !== null)
                 throw new PoppyError('conversation_not_found');
         }
@@ -223,7 +223,7 @@ export class PoppyConversations {
                     throw new PoppyError('message_id_conflict');
                 const existing = await this.options.store.getConversation(claim.conversationId);
                 if (existing) {
-                    // A retried first message: the conversation it already started (§7.3).
+                    // A retried first message: the conversation it already started (§8.3).
                     return { ...claim.response, conversationId: claim.conversationId };
                 }
                 // Claimed by a delivery that died before creating it: take it over.
@@ -299,13 +299,13 @@ export class PoppyConversations {
         // A Direct Conversation that closed without telling its parent: the parent is free.
         await this.options.store.updateConversation(conversation.id, { openDirectId: null });
     }
-    /** `POST {endpoint}/{id}/messages` — another message (§7.3). */
+    /** `POST {endpoint}/{id}/messages` — another message (§8.3). */
     async send(principal, conversationId, body) {
         const owned = await this.#owned(principal, conversationId);
         const actor = await this.actorOf(principal);
         const owner = ownerKey(principal);
         const fingerprint = messageFingerprint(conversationId, body);
-        // A retry is answered as before, whatever happened since (§7.3).
+        // A retry is answered as before, whatever happened since (§8.3).
         return this.#locked(conversationId, async () => {
             const conversation = (await this.options.store.getConversation(owned.id)) ?? owned;
             const content = hasContent(body.message);
@@ -335,7 +335,7 @@ export class PoppyConversations {
                 throw error;
             }
             const patch = { grant: this.#grant(principal, actor) };
-            // Once it is used signed in, the conversation belongs to that account (§7.2).
+            // Once it is used signed in, the conversation belongs to that account (§8.2).
             if (principal.signedIn && conversation.accountRef === null) {
                 patch.accountRef = await this.#accountOf(principal);
             }
@@ -371,12 +371,12 @@ export class PoppyConversations {
         if (hasContent(message))
             this.#kick(conversation.id);
     }
-    /** `GET {endpoint}/{id}/events` without streaming — read (and wait for) events (§7.5). */
+    /** `GET {endpoint}/{id}/events` without streaming — read (and wait for) events (§8.5). */
     async read(principal, conversationId, options) {
         const conversation = await this.#owned(principal, conversationId);
         return this.readOwned(conversation, options);
     }
-    /** A read of a conversation already checked — also what a POST with `wait` answers (§7.3). */
+    /** A read of a conversation already checked — also what a POST with `wait` answers (§8.3). */
     async readOwned(conversation, options) {
         await this.#maintain(conversation);
         let afterSeq = await this.#cursorSeq(conversation, options.cursor);
@@ -404,7 +404,7 @@ export class PoppyConversations {
         return this.#owned(principal, conversationId);
     }
     /**
-     * `GET {endpoint}/{id}/events` as SSE (§7.6): the events after `cursor`, then new ones as they
+     * `GET {endpoint}/{id}/events` as SSE (§8.6): the events after `cursor`, then new ones as they
      * come, with `text-delta` pieces of a reply being written in this process. Ends when `signal`
      * aborts, or once the conversation is closed and every event was sent.
      */
@@ -488,7 +488,7 @@ export class PoppyConversations {
             this.#bus.on(`event:${conversationId}`, done);
         });
     }
-    /** The position after which a read starts (§7.5): unknown → `invalid_cursor`, pruned → expired. */
+    /** The position after which a read starts (§8.5): unknown → `invalid_cursor`, pruned → expired. */
     async #cursorSeq(conversation, cursor) {
         if (cursor === undefined)
             return 0;
@@ -515,7 +515,7 @@ export class PoppyConversations {
             this.#kick(conversation.id);
         }
     }
-    /** `POST {endpoint}/{id}/handoff` — ask for a person at the Company (§7.9). */
+    /** `POST {endpoint}/{id}/handoff` — ask for a person at the Company (§8.9). */
     async requestHandoff(principal, conversationId) {
         const owned = await this.#owned(principal, conversationId);
         const conversation = await this.#locked(owned.id, async () => {
@@ -534,10 +534,10 @@ export class PoppyConversations {
         }
         const hooks = this.options.handoff;
         if (!hooks) {
-            // No people to hand off to: the Company Agent says so, and keeps the conversation (§7.9).
+            // No people to hand off to: the Company Agent says so, and keeps the conversation (§8.9).
             await this.#append(conversation.id, {
                 type: 'message',
-                message: this.#companyMessage(this.#texts.handoffUnavailable, undefined, 'agent'),
+                message: this.#companyMessage(this.#texts.handoffUnavailable, undefined, { type: 'agent' }),
             });
             return { status: conversation.status, responder: conversation.responder };
         }
@@ -565,7 +565,7 @@ export class PoppyConversations {
         }
         return { status: queued.status, responder: queued.responder };
     }
-    /** `POST {endpoint}/{id}/close` — close the conversation (§7.12). */
+    /** `POST {endpoint}/{id}/close` — close the conversation (§8.12). */
     async closeByAgent(principal, conversationId) {
         const conversation = await this.#owned(principal, conversationId);
         return this.close(conversation.id);
@@ -582,7 +582,7 @@ export class PoppyConversations {
         return conversation;
     }
     /**
-     * Close a conversation (§7.12): its open Direct Conversation first, a pending handoff is
+     * Close a conversation (§8.12): its open Direct Conversation first, a pending handoff is
      * cancelled, and a `closed` state event added. Nothing it started is undone. Idempotent.
      */
     async close(conversationId) {
@@ -627,14 +627,14 @@ export class PoppyConversations {
         }
         return { status: 'closed', responder: closed.responder };
     }
-    /** The Company Agent hands off to a person on its own (§7.9) — e.g. from one of your tools. */
+    /** The Company Agent hands off to a person on its own (§8.9) — e.g. from one of your tools. */
     async handoff(conversationId) {
         const conversation = await this.#require(conversationId);
         if (conversation.status === 'closed')
             throw new PoppyError('conversation_closed');
         return this.#handoff(conversation, 'company');
     }
-    /** A person at the Company joined: `responder` becomes `human` (§7.7). */
+    /** A person at the Company joined: `responder` becomes `human` (§8.7). */
     async humanJoined(conversationId) {
         return this.#locked(conversationId, async () => {
             const conversation = await this.#require(conversationId);
@@ -659,7 +659,7 @@ export class PoppyConversations {
     }
     /**
      * No one could take a queued handoff: the Company Agent says why, and the conversation goes back
-     * to `idle` with the agent (§7.9).
+     * to `idle` with the agent (§8.9).
      */
     async handoffUnavailable(conversationId, reason = this.#texts.handoffUnavailable) {
         return this.#locked(conversationId, async () => {
@@ -669,26 +669,26 @@ export class PoppyConversations {
             }
             await this.#append(conversationId, {
                 type: 'message',
-                message: this.#companyMessage(reason, undefined, 'agent'),
+                message: this.#companyMessage(reason, undefined, { type: 'agent' }),
             });
             const updated = await this.#setState(conversation, { status: 'idle', responder: 'agent' });
             return { status: updated.status, responder: updated.responder };
         });
     }
     /**
-     * Add a Company message — a person's (`sender: 'human'`, while they handle the conversation) or
+     * Add a Company message — a person's (`author.type: 'human'`, while they handle the conversation) or
      * an automated one. Answers the message's id.
      */
     async postMessage(conversationId, message) {
         const conversation = await this.#require(conversationId);
         if (conversation.status === 'closed')
             throw new PoppyError('conversation_closed');
-        const event = this.#companyMessage(message.text, message.data, message.sender);
+        const event = this.#companyMessage(message.text, message.data, message.author);
         await this.#append(conversationId, { type: 'message', message: event });
         return event.id;
     }
     /**
-     * Ask to talk with the User directly (§7.10): a `user_requested` event. Only the Personal Agent
+     * Ask to talk with the User directly (§8.10): a `user_requested` event. Only the Personal Agent
      * opens the Direct Conversation, once the User agrees.
      */
     async requestUser(conversationId, reason) {
@@ -829,7 +829,7 @@ export class PoppyConversations {
                         poppy: {
                             conversationId: conversation.id,
                             direct: conversation.parentId !== null,
-                            sender: last?.sender ?? 'agent',
+                            sender: last?.author?.type ?? 'agent',
                             signedIn: grant.signedIn,
                             context: conversation.context,
                         },
@@ -941,13 +941,13 @@ export class PoppyConversations {
     }
     /**
      * Write a turn's reply: a `message` event (text, and `data` for components and executed actions),
-     * then an `authorization` event when the turn needed a scope the token does not carry (§7.11).
+     * then an `authorization` event when the turn needed a scope the token does not carry (§8.11).
      */
     async #reply(conversation, grant, runId, turn) {
         const store = this.options.store;
         const current = await store.getConversation(conversation.id);
         await store.updateConversation(conversation.id, { activeRunId: null });
-        // A closed conversation takes no more events from its agent (§7.12).
+        // A closed conversation takes no more events from its agent (§8.12).
         if (!current || current.status === 'closed')
             return;
         const components = turn.components.map((frame) => ({
@@ -986,21 +986,21 @@ export class PoppyConversations {
         if (text !== '' || Object.keys(data).length > 0) {
             await this.#append(conversation.id, {
                 type: 'message',
-                message: this.#companyMessage(text, Object.keys(data).length > 0 ? data : undefined, 'agent', derivedPoppyId('msg', `reply:${runId}`)),
+                message: this.#companyMessage(text, Object.keys(data).length > 0 ? data : undefined, { type: 'agent' }, derivedPoppyId('msg', `reply:${runId}`)),
             }, `reply:${runId}`);
         }
         const missing = (turn.permission ?? []).filter((scope) => !grant.signedIn || !grant.scopes.includes(scope));
         if (missing.length > 0) {
             await this.#append(conversation.id, {
                 type: 'authorization',
-                error: grant.signedIn ? 'insufficient_scope' : 'sign_in_required',
+                error: 'insufficient_scope',
                 scope: missing.join(' '),
             }, `authorization:${runId}`);
             // In a Direct Conversation the User reads the messages, not the events: ask there too.
             if (conversation.parentId !== null) {
                 await this.#append(conversation.id, {
                     type: 'message',
-                    message: this.#companyMessage(this.#texts.signIn, undefined, 'agent', derivedPoppyId('msg', `sign-in:${runId}`)),
+                    message: this.#companyMessage(this.#texts.signIn, undefined, { type: 'agent' }, derivedPoppyId('msg', `sign-in:${runId}`)),
                 }, `sign-in:${runId}`);
             }
         }