@adonis-agora/agent 0.76.3 → 0.77.1

package/dist/src/poppy-connections/service.d.ts

@@ -0,0 +1,179 @@
+import type { CompanyClient, McpConnection, StoredKey } from '../poppy-client/index.js';
+import { AgentIdentity, OAuthError, PoppyError, ResourceAuthError } from '../poppy-client/index.js';
+import type { Actor } from '../types.js';
+import { type PoppyCompanyPolicy, type PoppyConnectionsConfig, type PoppyConnectionsTexts } from './config.js';
+import type { PoppyConnectionRecord, PoppyConnectionStore, PoppyPendingConnect } from './store.js';
+/** A Company outside the allow-list. The model is told plainly, and nothing is fetched. */
+export declare class PoppyCompanyNotAllowedError extends Error {
+    readonly domain: string;
+    constructor(domain: string);
+}
+/** One connection as the app and the model see it — never a token. */
+export interface PoppyConnectionView {
+    domain: string;
+    organization: string;
+    status: PoppyConnectionRecord['status'];
+    scope: string;
+    connectedSince: number | null;
+}
+/** What a connect page shows. */
+export type PoppyConnectPageData = {
+    kind: 'expired';
+} | {
+    kind: 'connected';
+    organization: string;
+} | {
+    kind: 'open';
+    id: string;
+    organization: string;
+    direct: boolean;
+    device: boolean;
+    mediated: {
+        name: string;
+        label: string;
+        secret: boolean;
+    }[] | null;
+};
+/** What `ask`/`request` bring back from the Company's agent. */
+export interface PoppyCompanyReply {
+    conversationId: string;
+    replies: {
+        text: string;
+        data?: Record<string, unknown>;
+    }[];
+    /** The Company said the token lacks something (§7.11). */
+    authorization?: {
+        error: string;
+        scope?: string;
+    };
+    status: string;
+}
+export interface PoppyConnectionsOptions {
+    config: PoppyConnectionsConfig;
+    store: PoppyConnectionStore;
+    secret: string;
+    production: boolean;
+    /** Called once a connect completes — the provider decides the parked `connect` call. */
+    onConnected?: (pending: PoppyPendingConnect) => Promise<void>;
+    log?: (line: string) => void;
+}
+/**
+ * This app's agent acting on other Poppy Companies for its users: the agent identity, the
+ * connections (sealed at rest), the connect flows and the calls the tools make.
+ *
+ * @experimental Tracks Personal Agent Protocol Draft 0.1 — will change as the spec evolves.
+ */
+export declare class PoppyConnections {
+    #private;
+    readonly texts: PoppyConnectionsTexts;
+    readonly path: string;
+    readonly baseUrl: string;
+    readonly insecureDev: boolean;
+    constructor(options: PoppyConnectionsOptions);
+    /** How long a connect link works, in ms (`connectTtlSeconds`, default 15 minutes). */
+    get connectTtlMs(): number;
+    /** The agent's display name (its `client_name`). */
+    get identityName(): string;
+    /** The app's agent identity (`client_id` = `{baseUrl}/{path}/agent.json`). */
+    identity(): Promise<AgentIdentity>;
+    ownerOf(actor: Actor): string;
+    /** The policy for `domain`, or `null` when it is not allow-listed (default: nothing is). */
+    policy(domain: string): PoppyCompanyPolicy | null;
+    /** The allow-listed Companies (when the allow-list is a list or a map). */
+    allowedCompanies(): {
+        domain: string;
+        label?: string;
+    }[];
+    /**
+     * The allow-listed domain the model meant by `company`. A model often names a company rather than
+     * its domain ("MeuProntoo", "meuprontoo.com" for `localhost:3841`): when `company` is not itself
+     * allowed, it resolves to the ONE allowed company whose label, or the organization of the
+     * owner's connection to it, it names. Ambiguous or unknown → `company` as given (then refused).
+     */
+    resolveCompany(owner: string, company: string): Promise<string>;
+    /**
+     * The organization an allow-listed company names itself in its `poppy.json` (cached ten
+     * minutes), or `undefined` when it cannot be reached — no owner, no sign-in needed.
+     */
+    organizationOf(domain: string): Promise<string | undefined>;
+    /** Run `fn` with this owner's client at `domain`, serialized per owner. */
+    withCompany<T>(owner: string, domain: string, fn: (client: CompanyClient, policy: PoppyCompanyPolicy) => Promise<T>): Promise<T>;
+    list(owner: string): Promise<PoppyConnectionView[]>;
+    /** The connection at `domain`, without contacting it. */
+    connection(owner: string, domain: string): Promise<PoppyConnectionView | null>;
+    /** Sign out at the Company (revokes the Account Token, §4.9) and mark the connection revoked. */
+    disconnect(owner: string, domain: string): Promise<boolean>;
+    /**
+     * Start a connect: the link the person opens (web or WhatsApp — it is a URL), bound to the parked
+     * `connect` call so completing it resumes the conversation. `id` makes a replayed call land on the
+     * same link.
+     */
+    startConnect(input: {
+        actor: Actor;
+        domain: string;
+        scope?: string;
+        threadId?: string;
+        runId?: string;
+        toolCallId?: string;
+        id?: string;
+    }): Promise<{
+        id: string;
+        url: string;
+        organization: string;
+        scope: string;
+    }>;
+    /** The connect started by one tool call (`runId`, `toolCallId`), if any. */
+    pendingFor(runId: string, toolCallId: string): Promise<PoppyPendingConnect | null>;
+    /**
+     * The connect id of one tool call (`runId:toolCallId`): a replayed call reaches the same link.
+     * Keyed with the app secret — the link is a bearer capability, so it must not be derivable.
+     */
+    connectIdFor(key: string): string;
+    connectUrl(id: string): string;
+    page(id: string): Promise<PoppyConnectPageData>;
+    /** Direct Sign-In (§4.5): the authorization URL to send the browser to. */
+    directUrl(id: string): Promise<string | null>;
+    /** The Direct Sign-In redirect back to `redirect_uri`. */
+    directCallback(params: URLSearchParams): Promise<{
+        ok: boolean;
+        organization: string | null;
+    }>;
+    /**
+     * Mediated Sign-In (§4.7) from this app's own page: the credentials go from the person's browser
+     * to this server and straight to the Company — never stored, logged, or shown to the model.
+     */
+    mediated(id: string, credentials: Record<string, string>): Promise<{
+        status: 'connected' | 'code_required' | 'failed' | 'expired';
+        sentTo?: string;
+    }>;
+    mediatedCode(id: string, code: string): Promise<{
+        status: 'connected' | 'code_required' | 'failed' | 'expired';
+        sentTo?: string;
+    }>;
+    /** Device Sign-In (§4.6): the code and the Company page where the person approves it. */
+    deviceStart(id: string): Promise<{
+        userCode: string;
+        verificationUri: string;
+    } | null>;
+    /** The device code already started for this connect, if any. */
+    deviceInfo(id: string): Promise<{
+        userCode: string;
+        verificationUri: string;
+    } | null>;
+    /** One device-code exchange, when the person says they approved. */
+    deviceCheck(id: string): Promise<'connected' | 'pending' | 'failed' | 'expired'>;
+    /** The Company's MCP server, with a Bearer token for it (§6). Closed by the caller. */
+    mcp(owner: string, domain: string): Promise<McpConnection>;
+    /**
+     * One exchange with the Company's agent (§7): `act: false` narrows the token to the read scopes
+     * (`policy.readScopes`, default `poppy:read`), so a question can never make the Company act;
+     * `act: true` uses the whole grant — the tools gate that behind the person's confirmation.
+     */
+    ask(owner: string, domain: string, text: string, options: {
+        act: boolean;
+    }): Promise<PoppyCompanyReply>;
+}
+/** Private EC JWKs (or poppy-client `StoredKey`s, or a JSON string of either) → `StoredKey[]`. */
+export declare function normalizeKeys(input: PoppyConnectionsConfig['identity']['keys']): Promise<StoredKey[]>;
+export { OAuthError, PoppyError, ResourceAuthError };
+//# sourceMappingURL=service.d.ts.map

package/dist/src/poppy-connections/service.d.ts.map

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