@adonis-agora/agent/dist/src/poppy/protocol.d.ts

Governed, durable-backed AI agent (chat + tool-calling + governance) for AdonisJS — part of the Agora ecosystem.

/**
 * The wire format of Personal Agent Protocol ("Poppy", Draft 0.1, §7) conversations: messages,
 * events, statuses and the error codes of §7.13. Hand-rolled like the A2A surface — the rules are
 * few and exact, and unknown fields are ignored everywhere (§3.1, §3.3).
 *
 * @experimental Tracks Personal Agent Protocol Draft 0.1 (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.
 */
/** The `protocol_version` this surface implements. */
export declare const POPPY_PROTOCOL_VERSION = "0.1";
/** The `type` of this surface's entry in `poppy.json` `agent.protocols` (§7.1). */
export declare const POPPY_PROTOCOL_TYPE = "poppy";
/** The account scopes the protocol defines (§4.4). Companies may add their own. */
export declare const POPPY_READ_SCOPE = "poppy:read";
export declare const POPPY_WRITE_SCOPE = "poppy:write";
export type PoppyStatus = 'working' | 'idle' | 'queued' | 'closed';
export type PoppyResponder = 'agent' | 'human';
export type PoppySender = 'agent' | 'human';
/** Facts about the User's situation (§7.4). Other fields are kept as sent. */
export interface PoppyContext {
    locale?: string;
    time_zone?: string;
    user_available?: boolean;
    [field: string]: unknown;
}
/** A message as the Personal Agent sends it (§7.4). */
export interface PoppyInboundMessage {
    id: string;
    sender: PoppySender;
    text?: string;
    data?: Record<string, unknown>;
    context?: PoppyContext;
}
/** A message as it appears in a `message` event (§7.5): `role` says which side it came from. */
export interface PoppyEventMessage {
    id: string;
    role: 'user' | 'company';
    sender: PoppySender;
    text?: string;
    data?: Record<string, unknown>;
    context?: PoppyContext;
}
export type PoppyEventType = 'message' | 'state' | 'authorization' | 'user_requested' | 'direct_opened' | 'direct_closed';
/** One event of a conversation (§7.5): `id`, `type`, `created_at`, and the type's own fields. */
export interface PoppyEvent {
    id: string;
    type: PoppyEventType | (string & {});
    created_at: string;
    [field: string]: unknown;
}
/** The type-specific fields of a new event — what the store appends. */
export type PoppyEventBody = {
    type: 'message';
    message: PoppyEventMessage;
} | {
    type: 'state';
    status: PoppyStatus;
    responder: PoppyResponder;
} | {
    type: 'authorization';
    error: 'sign_in_required' | 'insufficient_scope';
    scope?: string;
} | {
    type: 'user_requested';
    reason: string;
} | {
    type: 'direct_opened' | 'direct_closed';
    conversation_id: string;
};
/** The conversation errors of §7.13, plus the request errors this surface answers. */
declare const ERRORS: {
    readonly conversation_not_found: 404;
    readonly conversation_closed: 409;
    readonly direct_conversation_open: 409;
    readonly message_id_conflict: 409;
    readonly invalid_cursor: 400;
    readonly cursor_expired: 410;
    readonly invalid_request: 400;
    /** §3.3 — a request handled only with an extension the Personal Agent does not list. */
    readonly extension_required: 403;
    readonly sign_in_required: 403;
    readonly not_found: 404;
    readonly method_not_allowed: 405;
    readonly request_too_large: 413;
    readonly not_implemented: 501;
    readonly server_error: 500;
};
export type PoppyErrorCode = keyof typeof ERRORS;
/**
 * A Poppy error, answered as `{ "error": code, … }` like an OAuth error response (§7.13). `extra`
 * carries what a code adds — `conversation_id` for `direct_conversation_open`, `extension` for
 * `extension_required`. An app hook may throw one to refuse a request.
 */
export declare class PoppyError extends Error {
    readonly code: PoppyErrorCode;
    readonly extra: Record<string, unknown>;
    constructor(code: PoppyErrorCode, description?: string, extra?: Record<string, unknown>);
    get status(): number;
    toJSON(): Record<string, unknown>;
}
export declare function isPoppyId(value: unknown): value is string;
/** A new id of `kind` — `cnv_…`, `msg_…`, `evt_…`. */
export declare function newPoppyId(prefix: 'cnv' | 'msg'): string;
/** A stable id derived from `seed` — what lets a re-read turn produce the same company message. */
export declare function derivedPoppyId(prefix: 'msg', seed: string): string;
/** A validated `POST {endpoint}` / `POST {endpoint}/{id}/messages` body. */
export interface PoppySendBody {
    message: PoppyInboundMessage;
    /** Only on `POST {endpoint}`: start a Direct Conversation under this one (§7.10). */
    parentConversationId?: string;
}
/**
 * Parse a message request (§7.3, §7.4). Unknown fields — on the body, the message or its context —
 * are ignored, never refused (§3.3). Only the fields the protocol defines are kept.
 */
export declare function parseSendBody(raw: string, opts: {
    allowParent: boolean;
}): PoppySendBody;
/**
 * The fingerprint a retry is compared by (§7.3): the message's content and, for a first message,
 * the conversation it was addressed to. Unknown fields were dropped by the parser, so a retry that
 * adds one is still the same message.
 */
export declare function messageFingerprint(target: string, body: PoppySendBody): string;
/**
 * A request body that must be an empty JSON object (handoff, close) — anything else is tolerated:
 * extensions may add fields (§3.3). Only malformed JSON is refused.
 */
export declare function parseEmptyBody(raw: string): void;
export {};
//# sourceMappingURL=protocol.d.ts.map