@paneui/core 0.0.4 → 0.0.6

package/dist/client.d.ts

@@ -1,4 +1,5 @@
-import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, PaneEvent, SessionState, TasteInfo } from "./types.js";
+import type { ArtifactRecord, ArtifactSummary, ArtifactType, ArtifactVersion, CreateArtifactResponse, CreateSessionRequest, CreateSessionResponse, EventsPage, FeedbackPage, FeedbackSubmission, FeedbackType, KeyInfo, MintParticipantResponse, PaneEvent, ParticipantsList, SessionState, SessionsPage, TasteInfo } from "./types.js";
+import type { ListSessionsQuery } from "./schemas.js";
 export interface ClientOptions {
     /** Relay base URL, e.g. https://pane.example.com. Trailing slash is trimmed. */
     url: string;
@@ -202,6 +203,47 @@ export declare class PaneClient {
         limit?: number;
         before?: string;
     }): Promise<FeedbackPage>;
+    /**
+     * GET /v1/sessions — list the calling agent's sessions. Default filter is
+     * `status=open` (effective status — respects expiresAt). Response items
+     * carry NO secrets: no participant token plaintext, no callback URL, no
+     * metadata or input_data. Use `participant_id` from the list as the handle
+     * for {@link revokeParticipant}; use {@link mintParticipant} to issue a
+     * fresh URL when the original was lost.
+     */
+    listSessions(opts?: ListSessionsQuery): Promise<SessionsPage>;
+    /**
+     * GET /v1/sessions/:id/participants — list every participant on one
+     * session (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * on the relay, so the full list is returned with no pagination.
+     * Use this to find the `participant_id` you need to pass to
+     * {@link revokeParticipant}, or to audit revoked rows.
+     */
+    listParticipants(sessionId: string): Promise<ParticipantsList>;
+    /**
+     * POST /v1/sessions/:id/participants — mint a fresh participant URL for an
+     * existing session. The one-shot recovery primitive when the original URL
+     * was dropped: the session keeps its event log, artifact pin, and created_at.
+     * v1 supports `kind: "human"` only.
+     *
+     * The plaintext token is returned EXACTLY ONCE in the response — the relay
+     * stores only the hash. Save the response (e.g. pipe to a JSONL log) before
+     * delivering the URL to the human.
+     */
+    mintParticipant(sessionId: string, opts?: {
+        kind?: "human";
+    }): Promise<MintParticipantResponse>;
+    /**
+     * DELETE /v1/sessions/:id/participants/:participant_id — revoke a single
+     * participant URL. The session's other participants (and the agent's own
+     * WebSocket) are untouched. Idempotent: revoking an unknown or already-
+     * revoked participant returns 204. The agent participant cannot be revoked
+     * via this endpoint — use {@link deleteSession} instead.
+     *
+     * Existing WebSocket connections held under the revoked token are NOT
+     * actively kicked in v1; new HTTP and WS connections are refused.
+     */
+    revokeParticipant(sessionId: string, participantId: string): Promise<void>;
     /**
      * DELETE /v1/sessions/:id — close/delete a session. Idempotent on the relay
      * side (an already-closed session still returns 204 with no body).
@@ -215,4 +257,156 @@ export declare class PaneClient {
      * instead of swallowing it.
      */
     deleteArtifact(idOrSlug: string): Promise<void>;
+    /**
+     * Upload a blob to the relay. Returns a `BlobRef` that can be referenced
+     * in event payloads (the relay's `format: pane-blob-id` schema vocab
+     * validates the id) or in `pane create --input-data`.
+     *
+     * Scope defaults to "agent" (reusable across the agent's sessions). For
+     * `scope: "session"` pass `sessionId`; for `scope: "artifact"` pass
+     * `artifactId`. The agent must own the referenced session / artifact;
+     * cross-tenant attempts return blob_not_found.
+     *
+     * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
+     * leading bytes and may reject with mime_mismatch / mime_disallowed.
+     *
+     * Backed by the relay's multipart `POST /v1/blobs` (the fallback path).
+     * For large uploads (>1 MB on hosted Azure) call `presignBlob()` +
+     * `confirmBlob()` instead — those use SAS direct-to-storage and don't
+     * stream bytes through the relay.
+     */
+    uploadBlob(file: Blob | Buffer | Uint8Array, opts?: UploadBlobOptions): Promise<BlobRef>;
+    /** GET /v1/blobs/:id — download bytes as an ArrayBuffer. */
+    downloadBlob(blobId: string): Promise<ArrayBuffer>;
+    /**
+     * GET a blob's metadata only — useful before downloading large blobs, or
+     * for `pane blob show <id>` which doesn't want the bytes. Returns the full
+     * BlobRef (the same shape POST /v1/blobs returns): id, scope, mime, size,
+     * sha256, filename, width, height, status, scope FKs, timestamps.
+     *
+     * Backed by GET /v1/blobs/:id/metadata which serves the JSON BlobRef
+     * without streaming the bytes — cheap on the relay and avoids the
+     * encrypt-at-rest decrypt cost when only the metadata is needed.
+     */
+    getBlob(blobId: string): Promise<BlobRef>;
+    /** DELETE /v1/blobs/:id — soft-delete (idempotent). */
+    deleteBlob(blobId: string): Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Mint a `/b/<token>` capability URL for `blobId`. Default TTL is set by
+     * the relay (24h agent, session-TTL session, 30d artifact). `once: true`
+     * tokens self-delete on first GET.
+     */
+    mintBlobToken(blobId: string, opts?: {
+        ttlSeconds?: number;
+        once?: boolean;
+    }): Promise<BlobTokenMintResponse>;
+    /** Revoke a previously-minted token. Idempotent. */
+    revokeBlobToken(blobId: string, tokenId: string): Promise<{
+        token_id: string;
+        revoked: true;
+    }>;
+    /**
+     * GET /v1/blobs — list YOUR agent's non-deleted blobs (newest first).
+     * Paginated via opaque cursor: when `next_cursor` is non-null, pass it
+     * back as `cursor` on the next call.
+     */
+    listBlobs(opts?: ListBlobsOptions): Promise<{
+        items: BlobRef[];
+        next_cursor: string | null;
+    }>;
+    /**
+     * GET /v1/blobs/:id/tokens — enumerate the capability tokens minted
+     * against one blob, including revoked rows (for audit). The plaintext
+     * token is NEVER returned — it isn't stored, only its sha256 is.
+     */
+    listBlobTokens(blobId: string): Promise<BlobTokenListResponse>;
+    /**
+     * Issue a presigned PUT URL for direct-to-storage upload. Returns the
+     * upload URL + the blob_id (already reserved in the relay's DB with
+     * status=pending) + expiry. After PUTting the bytes to the URL, call
+     * `confirmBlob(blob_id)` to finalise.
+     *
+     * Filesystem backend returns 501 not_implemented — use uploadBlob()
+     * (multipart fallback) instead. Azure backend returns a SAS URL.
+     */
+    presignBlob(opts: PresignBlobOptions): Promise<{
+        blob_id: string;
+        upload_url: string;
+        expires_at: string;
+    }>;
+    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    confirmBlob(blobId: string): Promise<BlobRef>;
+}
+/** Per-blob metadata as returned by `POST /v1/blobs` and friends. */
+export interface BlobRef {
+    blob_id: string;
+    scope: "agent" | "session" | "artifact";
+    mime: string;
+    size: number;
+    sha256: string;
+    url?: string;
+    width?: number | null;
+    height?: number | null;
+    filename?: string | null;
+    status?: string;
+    session_id?: string | null;
+    artifact_id?: string | null;
+    created_at?: string;
+    confirmed_at?: string | null;
+    deleted_at?: string | null;
+}
+export interface UploadBlobOptions {
+    scope?: "agent" | "session" | "artifact";
+    sessionId?: string;
+    artifactId?: string;
+    /** Declared Content-Type. Defaults to `application/octet-stream`. The
+     *  relay sniffs leading bytes and may reject with `mime_mismatch`. */
+    mime?: string;
+    /** Optional display name (the relay records it for UX; never a path component). */
+    filename?: string;
+}
+export interface PresignBlobOptions {
+    mime: string;
+    size: number;
+    sha256: string;
+    scope?: "agent" | "session" | "artifact";
+    sessionId?: string;
+    artifactId?: string;
+    filename?: string;
+}
+export interface BlobTokenMintResponse {
+    token_id: string;
+    token: string;
+    token_prefix: string;
+    url: string;
+    expires_at: string;
+    once: boolean;
+}
+/** Options for `listBlobs()` — opaque cursor + page-size knob. */
+export interface ListBlobsOptions {
+    /** Opaque pagination cursor from a prior `next_cursor`. */
+    cursor?: string;
+    /** Page size; relay clamps to 1..100. Defaults to the relay default (50). */
+    limit?: number;
+}
+/** One row in the response from `listBlobTokens()`. */
+export interface BlobTokenAuditEntry {
+    token_id: string;
+    token_prefix: string;
+    expires_at: string;
+    once: boolean;
+    created_at: string;
+    last_used_at: string | null;
+    use_count: number;
+    /** Non-null when the token has been revoked. Expired-but-unrevoked rows
+     *  carry `revoked_at: null` and an `expires_at` in the past — both are
+     *  useful for audit. */
+    revoked_at: string | null;
+}
+/** Shape returned by `listBlobTokens()`. */
+export interface BlobTokenListResponse {
+    blob_id: string;
+    items: BlobTokenAuditEntry[];
 }

package/dist/client.js

@@ -125,6 +125,7 @@ export class PaneClient {
     async createSession(req) {
         const r = await this.call("POST", "/v1/sessions", {
             artifact: req.artifact,
+            title: req.title,
             input_data: req.input_data,
             participants: req.participants,
             ttl: req.ttl,
@@ -341,6 +342,74 @@ export class PaneClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * GET /v1/sessions — list the calling agent's sessions. Default filter is
+     * `status=open` (effective status — respects expiresAt). Response items
+     * carry NO secrets: no participant token plaintext, no callback URL, no
+     * metadata or input_data. Use `participant_id` from the list as the handle
+     * for {@link revokeParticipant}; use {@link mintParticipant} to issue a
+     * fresh URL when the original was lost.
+     */
+    async listSessions(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.status !== undefined)
+            q.set("status", opts.status);
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts.cursor !== undefined && opts.cursor !== "")
+            q.set("cursor", opts.cursor);
+        if (opts.artifact_id !== undefined && opts.artifact_id !== "")
+            q.set("artifact_id", opts.artifact_id);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/sessions${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/sessions/:id/participants — list every participant on one
+     * session (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+     * on the relay, so the full list is returned with no pagination.
+     * Use this to find the `participant_id` you need to pass to
+     * {@link revokeParticipant}, or to audit revoked rows.
+     */
+    async listParticipants(sessionId) {
+        const r = await this.call("GET", `/v1/sessions/${encodeURIComponent(sessionId)}/participants`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/sessions/:id/participants — mint a fresh participant URL for an
+     * existing session. The one-shot recovery primitive when the original URL
+     * was dropped: the session keeps its event log, artifact pin, and created_at.
+     * v1 supports `kind: "human"` only.
+     *
+     * The plaintext token is returned EXACTLY ONCE in the response — the relay
+     * stores only the hash. Save the response (e.g. pipe to a JSONL log) before
+     * delivering the URL to the human.
+     */
+    async mintParticipant(sessionId, opts = {}) {
+        const r = await this.call("POST", `/v1/sessions/${encodeURIComponent(sessionId)}/participants`, { kind: opts.kind ?? "human" });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/sessions/:id/participants/:participant_id — revoke a single
+     * participant URL. The session's other participants (and the agent's own
+     * WebSocket) are untouched. Idempotent: revoking an unknown or already-
+     * revoked participant returns 204. The agent participant cannot be revoked
+     * via this endpoint — use {@link deleteSession} instead.
+     *
+     * Existing WebSocket connections held under the revoked token are NOT
+     * actively kicked in v1; new HTTP and WS connections are refused.
+     */
+    async revokeParticipant(sessionId, participantId) {
+        const r = await this.call("DELETE", `/v1/sessions/${encodeURIComponent(sessionId)}/participants/${encodeURIComponent(participantId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
     /**
      * DELETE /v1/sessions/:id — close/delete a session. Idempotent on the relay
      * side (an already-closed session still returns 204 with no body).
@@ -362,4 +431,212 @@ export class PaneClient {
         if (!r.ok)
             this.fail(r);
     }
+    // ------------------------------------------------------------------------
+    // Blobs (v0.1.0). Three-scope binary attachments with multipart upload.
+    // See proposal pane#152 for the full design.
+    // ------------------------------------------------------------------------
+    /**
+     * Upload a blob to the relay. Returns a `BlobRef` that can be referenced
+     * in event payloads (the relay's `format: pane-blob-id` schema vocab
+     * validates the id) or in `pane create --input-data`.
+     *
+     * Scope defaults to "agent" (reusable across the agent's sessions). For
+     * `scope: "session"` pass `sessionId`; for `scope: "artifact"` pass
+     * `artifactId`. The agent must own the referenced session / artifact;
+     * cross-tenant attempts return blob_not_found.
+     *
+     * MIME is inferred from `mime` if supplied; otherwise the relay sniffs
+     * leading bytes and may reject with mime_mismatch / mime_disallowed.
+     *
+     * Backed by the relay's multipart `POST /v1/blobs` (the fallback path).
+     * For large uploads (>1 MB on hosted Azure) call `presignBlob()` +
+     * `confirmBlob()` instead — those use SAS direct-to-storage and don't
+     * stream bytes through the relay.
+     */
+    async uploadBlob(file, opts = {}) {
+        const fd = new FormData();
+        let blob;
+        if (file instanceof Blob) {
+            blob = file;
+        }
+        else {
+            // Buffer / Uint8Array path — wrap in a Blob with the declared MIME.
+            // Copy into a freshly allocated Uint8Array so the buffer type
+            // narrows from `ArrayBufferLike` (which includes SharedArrayBuffer)
+            // to `ArrayBuffer` specifically — the Blob constructor accepts only
+            // the latter under @types/node ≥25 + TS ≥5.7's generic narrowing of
+            // Uint8Array<TArrayBuffer>. `new Uint8Array(length)` returns
+            // `Uint8Array<ArrayBuffer>` by construction, satisfying BlobPart
+            // without a type cast. The extra copy is one walk over the bytes —
+            // negligible vs the network upload that follows.
+            const src = file instanceof Uint8Array ? file : new Uint8Array(file);
+            const u8 = new Uint8Array(src.byteLength);
+            u8.set(src);
+            blob = new Blob([u8], {
+                type: opts.mime ?? "application/octet-stream",
+            });
+        }
+        fd.set("file", blob, opts.filename ?? "blob");
+        if (opts.scope)
+            fd.set("scope", opts.scope);
+        if (opts.sessionId)
+            fd.set("session_id", opts.sessionId);
+        if (opts.artifactId)
+            fd.set("artifact_id", opts.artifactId);
+        if (opts.filename)
+            fd.set("filename", opts.filename);
+        const url = this.base + "/v1/blobs";
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method: "POST",
+                headers: {
+                    authorization: "Bearer " + this.apiKey,
+                    ...(this.cliVersion ? { "x-pane-cli-version": this.cliVersion } : {}),
+                },
+                body: fd,
+            });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new PaneApiError(0, "fetch_error", msg);
+        }
+        const text = await res.text().catch(() => "");
+        let data;
+        try {
+            data = text ? JSON.parse(text) : null;
+        }
+        catch {
+            throw new PaneApiError(res.status, "non_json_response", `relay returned a non-JSON body (status ${res.status})`);
+        }
+        if (!res.ok) {
+            this.fail({ ok: false, status: res.status, data });
+        }
+        return data;
+    }
+    /** GET /v1/blobs/:id — download bytes as an ArrayBuffer. */
+    async downloadBlob(blobId) {
+        const url = this.base + "/v1/blobs/" + encodeURIComponent(blobId);
+        const res = await this.fetchImpl(url, {
+            method: "GET",
+            headers: {
+                authorization: "Bearer " + this.apiKey,
+                ...(this.cliVersion ? { "x-pane-cli-version": this.cliVersion } : {}),
+            },
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = null;
+            }
+            this.fail({ ok: false, status: res.status, data });
+        }
+        return res.arrayBuffer();
+    }
+    /**
+     * GET a blob's metadata only — useful before downloading large blobs, or
+     * for `pane blob show <id>` which doesn't want the bytes. Returns the full
+     * BlobRef (the same shape POST /v1/blobs returns): id, scope, mime, size,
+     * sha256, filename, width, height, status, scope FKs, timestamps.
+     *
+     * Backed by GET /v1/blobs/:id/metadata which serves the JSON BlobRef
+     * without streaming the bytes — cheap on the relay and avoids the
+     * encrypt-at-rest decrypt cost when only the metadata is needed.
+     */
+    async getBlob(blobId) {
+        const r = await this.call("GET", "/v1/blobs/" + encodeURIComponent(blobId) + "/metadata");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/blobs/:id — soft-delete (idempotent). */
+    async deleteBlob(blobId) {
+        const r = await this.call("DELETE", "/v1/blobs/" + encodeURIComponent(blobId));
+        if (!r.ok)
+            this.fail(r);
+        return { deleted: true };
+    }
+    /**
+     * Mint a `/b/<token>` capability URL for `blobId`. Default TTL is set by
+     * the relay (24h agent, session-TTL session, 30d artifact). `once: true`
+     * tokens self-delete on first GET.
+     */
+    async mintBlobToken(blobId, opts = {}) {
+        const r = await this.call("POST", "/v1/blobs/" + encodeURIComponent(blobId) + "/tokens", { ttl_seconds: opts.ttlSeconds, once: opts.once });
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /** Revoke a previously-minted token. Idempotent. */
+    async revokeBlobToken(blobId, tokenId) {
+        const r = await this.call("DELETE", "/v1/blobs/" +
+            encodeURIComponent(blobId) +
+            "/tokens/" +
+            encodeURIComponent(tokenId));
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * GET /v1/blobs — list YOUR agent's non-deleted blobs (newest first).
+     * Paginated via opaque cursor: when `next_cursor` is non-null, pass it
+     * back as `cursor` on the next call.
+     */
+    async listBlobs(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.cursor !== undefined)
+            params.set("cursor", opts.cursor);
+        if (opts.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        const r = await this.call("GET", "/v1/blobs" + (qs ? "?" + qs : ""));
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * GET /v1/blobs/:id/tokens — enumerate the capability tokens minted
+     * against one blob, including revoked rows (for audit). The plaintext
+     * token is NEVER returned — it isn't stored, only its sha256 is.
+     */
+    async listBlobTokens(blobId) {
+        const r = await this.call("GET", "/v1/blobs/" + encodeURIComponent(blobId) + "/tokens");
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /**
+     * Issue a presigned PUT URL for direct-to-storage upload. Returns the
+     * upload URL + the blob_id (already reserved in the relay's DB with
+     * status=pending) + expiry. After PUTting the bytes to the URL, call
+     * `confirmBlob(blob_id)` to finalise.
+     *
+     * Filesystem backend returns 501 not_implemented — use uploadBlob()
+     * (multipart fallback) instead. Azure backend returns a SAS URL.
+     */
+    async presignBlob(opts) {
+        const r = await this.call("POST", "/v1/blobs/presign", {
+            mime: opts.mime,
+            size: opts.size,
+            sha256: opts.sha256,
+            scope: opts.scope,
+            session_id: opts.sessionId,
+            artifact_id: opts.artifactId,
+            filename: opts.filename,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
+    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    async confirmBlob(blobId) {
+        const r = await this.call("POST", "/v1/blobs/" + encodeURIComponent(blobId) + "/confirm");
+        if (!r.ok)
+            this.fail(r);
+        return r.data;
+    }
 }

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { PaneClient, PaneApiError } from "./client.js";
-export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, } from "./client.js";
+export type { ClientOptions, RelayResponse, CreateArtifactRequest, CreateArtifactVersionRequest, PatchArtifactMetadataRequest, BlobRef, UploadBlobOptions, PresignBlobOptions, BlobTokenMintResponse, ListBlobsOptions, BlobTokenAuditEntry, BlobTokenListResponse, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { registerAgent } from "./register.js";
 export type { RegisterAgentOptions, RegisterAgentResult } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, } from "./schemas.js";
-export type { CreateSessionInput } from "./schemas.js";
+export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listSessionsStatusSchema, listSessionsQuerySchema, mintParticipantSchema, } from "./schemas.js";
+export type { CreateSessionInput, ListSessionsStatus, ListSessionsQuery, MintParticipantInput, } from "./schemas.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";
-export type { AuthorKind, PaneEvent, Artifact, ArtifactType, ArtifactVersion, ArtifactRecord, ArtifactSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreateSessionRequest, CreateSessionResponse, SessionState, EventsPage, RelayError, } from "./types.js";
+export type { AuthorKind, PaneEvent, Artifact, ArtifactType, ArtifactVersion, ArtifactRecord, ArtifactSummary, CreateArtifactResponse, KeyInfo, TasteInfo, FeedbackType, FeedbackSubmission, FeedbackRecord, FeedbackPage, Callback, CreateSessionRequest, CreateSessionResponse, SessionState, EventsPage, ParticipantSummary, ParticipantsList, SessionSummary, SessionsPage, MintParticipantResponse, RelayError, } from "./types.js";

package/dist/index.js

@@ -3,5 +3,5 @@
 export { PaneClient, PaneApiError } from "./client.js";
 export { openStream } from "./stream.js";
 export { registerAgent } from "./register.js";
-export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, } from "./schemas.js";
+export { artifactSchema, callbackSchema, createSessionSchema, artifactTypeSchema, createArtifactSchema, createArtifactVersionSchema, patchArtifactMetadataSchema, feedbackTypeSchema, submitFeedbackSchema, listSessionsStatusSchema, listSessionsQuerySchema, mintParticipantSchema, } from "./schemas.js";
 export { MAX_EVENT_TYPE_LENGTH, MAX_IDEMPOTENCY_KEY_LENGTH, MAX_RESPONSE_SNIPPET_LENGTH, MAX_FRAME_SNIPPET_LENGTH, } from "./limits.js";

package/dist/schemas.d.ts

@@ -1,211 +1,108 @@
 import { z } from "zod";
-export declare const artifactTypeSchema: z.ZodEnum<["html-inline", "html-ref"]>;
-export declare const artifactSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+export declare const artifactTypeSchema: z.ZodEnum<{
+    "html-inline": "html-inline";
+    "html-ref": "html-ref";
+}>;
+export declare const artifactSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"html-inline">;
     source: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline";
-    source: string;
-}, {
-    type: "html-inline";
-    source: string;
-}>, z.ZodObject<{
+}, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"html-ref">;
     source: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    type: "html-ref";
-    source: string;
-}, {
-    type: "html-ref";
-    source: string;
-}>]>;
+}, z.core.$strip>], "type">;
 export declare const callbackSchema: z.ZodObject<{
     url: z.ZodString;
-    events: z.ZodArray<z.ZodString, "many">;
+    events: z.ZodArray<z.ZodString>;
     secret: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    url: string;
-    events: string[];
-    secret: string;
-}, {
-    url: string;
-    events: string[];
-    secret: string;
-}>;
+}, z.core.$strip>;
 export declare const createSessionSchema: z.ZodObject<{
-    artifact: z.ZodEffects<z.ZodUnion<[z.ZodObject<{
+    artifact: z.ZodUnion<readonly [z.ZodObject<{
         id: z.ZodString;
         version: z.ZodOptional<z.ZodNumber>;
-    }, "strip", z.ZodTypeAny, {
-        id: string;
-        version?: number | undefined;
-    }, {
-        id: string;
-        version?: number | undefined;
-    }>, z.ZodObject<{
+    }, z.core.$strip>, z.ZodObject<{
         source: z.ZodString;
-        type: z.ZodEnum<["html-inline", "html-ref"]>;
+        type: z.ZodEnum<{
+            "html-inline": "html-inline";
+            "html-ref": "html-ref";
+        }>;
         event_schema: z.ZodOptional<z.ZodUnknown>;
-    }, "strip", z.ZodTypeAny, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    }, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    }>]>, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    }, {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    }>;
+        input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>]>;
     input_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     participants: z.ZodOptional<z.ZodObject<{
         humans: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        humans: number;
-    }, {
-        humans: number;
-    }>>;
+    }, z.core.$strip>>;
     ttl: z.ZodOptional<z.ZodNumber>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     callback: z.ZodOptional<z.ZodObject<{
         url: z.ZodString;
-        events: z.ZodArray<z.ZodString, "many">;
+        events: z.ZodArray<z.ZodString>;
         secret: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        url: string;
-        events: string[];
-        secret: string;
-    }, {
-        url: string;
-        events: string[];
-        secret: string;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    artifact: {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    };
-    input_data?: Record<string, unknown> | undefined;
-    participants?: {
-        humans: number;
-    } | undefined;
-    ttl?: number | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    callback?: {
-        url: string;
-        events: string[];
-        secret: string;
-    } | undefined;
-}, {
-    artifact: {
-        type: "html-inline" | "html-ref";
-        source: string;
-        event_schema?: unknown;
-    } | {
-        id: string;
-        version?: number | undefined;
-    };
-    input_data?: Record<string, unknown> | undefined;
-    participants?: {
-        humans: number;
-    } | undefined;
-    ttl?: number | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    callback?: {
-        url: string;
-        events: string[];
-        secret: string;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const createArtifactSchema: z.ZodObject<{
     name: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     source: z.ZodString;
-    type: z.ZodEnum<["html-inline", "html-ref"]>;
+    type: z.ZodEnum<{
+        "html-inline": "html-inline";
+        "html-ref": "html-ref";
+    }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    name: string;
-    event_schema?: unknown;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-}, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    name: string;
-    event_schema?: unknown;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-    input_schema?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export declare const createArtifactVersionSchema: z.ZodObject<{
     source: z.ZodString;
-    type: z.ZodEnum<["html-inline", "html-ref"]>;
+    type: z.ZodEnum<{
+        "html-inline": "html-inline";
+        "html-ref": "html-ref";
+    }>;
     event_schema: z.ZodOptional<z.ZodUnknown>;
     input_schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, "strip", z.ZodTypeAny, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    event_schema?: unknown;
-    input_schema?: Record<string, unknown> | undefined;
-}, {
-    type: "html-inline" | "html-ref";
-    source: string;
-    event_schema?: unknown;
-    input_schema?: Record<string, unknown> | undefined;
-}>;
+}, z.core.$strip>;
 export declare const patchArtifactMetadataSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodString>;
     slug: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-}, "strip", z.ZodTypeAny, {
-    name?: string | undefined;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
-}, {
-    name?: string | undefined;
-    slug?: string | undefined;
-    description?: string | undefined;
-    tags?: string[] | undefined;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const feedbackTypeSchema: z.ZodEnum<{
+    bug: "bug";
+    feature: "feature";
+    note: "note";
 }>;
-export declare const feedbackTypeSchema: z.ZodEnum<["bug", "feature", "note"]>;
 export declare const submitFeedbackSchema: z.ZodObject<{
-    type: z.ZodEnum<["bug", "feature", "note"]>;
-    message: z.ZodPipeline<z.ZodEffects<z.ZodString, string, string>, z.ZodString>;
+    type: z.ZodEnum<{
+        bug: "bug";
+        feature: "feature";
+        note: "note";
+    }>;
+    message: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodString>;
     session_id: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    type: "bug" | "feature" | "note";
-    message: string;
-    session_id?: string | undefined;
-}, {
-    type: "bug" | "feature" | "note";
-    message: string;
-    session_id?: string | undefined;
-}>;
+}, z.core.$strip>;
 /** @deprecated use `CreateSessionRequest` from ./types.js (same type). */
 export type CreateSessionInput = z.infer<typeof createSessionSchema>;
+export declare const listSessionsStatusSchema: z.ZodEnum<{
+    open: "open";
+    closed: "closed";
+    all: "all";
+}>;
+export type ListSessionsStatus = z.infer<typeof listSessionsStatusSchema>;
+export declare const listSessionsQuerySchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        closed: "closed";
+        all: "all";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    artifact_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ListSessionsQuery = z.infer<typeof listSessionsQuerySchema>;
+export declare const mintParticipantSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"human">;
+}, z.core.$strip>;
+export type MintParticipantInput = z.infer<typeof mintParticipantSchema>;

package/dist/schemas.js

@@ -25,6 +25,14 @@ const inlineArtifactSchema = z.object({
     // Optional: omit for a view-only one-off (a report/dashboard the human only
     // views — the session then accepts no page/agent events).
     event_schema: z.unknown().optional(),
+    // Optional: when present, the session's `input_data` is validated against
+    // this JSON Schema before the session row is created — and any blob refs
+    // declared at `format: pane-blob-id` sites become reachable from the page
+    // via `window.pane.downloadBlob()`. Without this, blob refs in
+    // `input_data` are silently unreachable for inline sessions (the
+    // participant blob-download bridge walks input_data against the artifact
+    // version's inputSchema; no schema means no walkable sites). See #208.
+    input_schema: z.record(z.string(), z.unknown()).optional(),
 });
 // The reference form for POST /v1/sessions — instances an existing named
 // artifact. `id` accepts the artifact id or its slug; `version` is optional
@@ -47,11 +55,16 @@ const sessionArtifactSchema = z
 });
 export const createSessionSchema = z.object({
     artifact: sessionArtifactSchema,
-    input_data: z.record(z.unknown()).optional(),
+    input_data: z.record(z.string(), z.unknown()).optional(),
     participants: z.object({ humans: z.number().int().positive() }).optional(),
     ttl: z.number().int().positive().optional(),
-    metadata: z.record(z.unknown()).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
     callback: callbackSchema.optional(),
+    // Tab title for the human's browser. Optional on the wire because the relay
+    // also accepts the implicit fallback (an Artifact.name on the reference
+    // form). The relay enforces "required-or-fallback" + length/control-char
+    // rules — Zod only confirms it's a string here.
+    title: z.string().optional(),
 });
 // POST /v1/artifacts — create a named, reusable artifact plus its v1 content.
 export const createArtifactSchema = z.object({
@@ -63,7 +76,7 @@ export const createArtifactSchema = z.object({
     type: artifactTypeSchema,
     // Optional: omit for a view-only artifact (no event vocabulary).
     event_schema: z.unknown().optional(),
-    input_schema: z.record(z.unknown()).optional(),
+    input_schema: z.record(z.string(), z.unknown()).optional(),
 });
 // POST /v1/artifacts/:id/versions — append a new version (content only).
 export const createArtifactVersionSchema = z.object({
@@ -71,7 +84,7 @@ export const createArtifactVersionSchema = z.object({
     type: artifactTypeSchema,
     // Optional: omit for a view-only artifact (no event vocabulary).
     event_schema: z.unknown().optional(),
-    input_schema: z.record(z.unknown()).optional(),
+    input_schema: z.record(z.string(), z.unknown()).optional(),
 });
 // PATCH /v1/artifacts/:id — update head metadata only (never content).
 export const patchArtifactMetadataSchema = z.object({
@@ -92,3 +105,19 @@ export const submitFeedbackSchema = z.object({
         .pipe(z.string().min(1).max(4000)),
     session_id: z.string().min(1).optional(),
 });
+// GET /v1/sessions — list the calling agent's sessions. The relay also
+// re-parses these on its side (defence in depth); this schema is for the CLI
+// to fail fast with a clear error before a round trip.
+export const listSessionsStatusSchema = z.enum(["open", "closed", "all"]);
+export const listSessionsQuerySchema = z.object({
+    status: listSessionsStatusSchema.optional(),
+    limit: z.number().int().positive().max(200).optional(),
+    cursor: z.string().min(1).optional(),
+    artifact_id: z.string().min(1).optional(),
+});
+// POST /v1/sessions/:id/participants — mint a fresh participant URL for an
+// existing session. v1 supports human participants only (the agent token is
+// minted at session-create and cannot be re-minted via this endpoint).
+export const mintParticipantSchema = z.object({
+    kind: z.literal("human"),
+});

package/dist/types.d.ts

@@ -52,6 +52,9 @@ export interface CreateSessionResponse {
         agent_stream: string;
     };
     expires_at: string;
+    /** The resolved tab title persisted on the session (the agent's value, or
+     * the Artifact.name fallback). */
+    title: string;
 }
 /** Response from GET /v1/sessions/:id. */
 export interface SessionState {
@@ -61,6 +64,8 @@ export interface SessionState {
     artifact_id: string;
     artifact_version_id: string;
     artifact_version: number;
+    /** The tab title this session was created with (frozen for its lifetime). */
+    title: string;
     metadata: Record<string, unknown> | null;
     input_data: Record<string, unknown> | null;
     created_at: string;
@@ -71,6 +76,66 @@ export interface EventsPage {
     events: PaneEvent[];
     next_cursor: string | null;
 }
+/** A non-secret summary of one participant on a session — safe to list. */
+export interface ParticipantSummary {
+    /** The revoke handle (Participant.id). */
+    participant_id: string;
+    /** "agent" or "human". The agent's own participant is always present. */
+    kind: "agent" | "human";
+    /** Short, non-secret correlator for a saved URL ("tok_h_..." / "tok_a_..."). */
+    token_prefix: string;
+    /** ISO timestamp of first WebSocket connect, or null if never joined. */
+    joined_at: string | null;
+    /** ISO timestamp the participant was revoked; null while still active. */
+    revoked_at: string | null;
+}
+/** A row in the GET /v1/sessions list response (no secrets, lean). */
+export interface SessionSummary {
+    session_id: string;
+    /** Tab title (required column; agent input or Artifact.name fallback). */
+    title: string;
+    /** Effective status — respects expiresAt projection (the column may say
+     *  "open" while `expires_at` is in the past; the projection reports "closed"). */
+    status: "open" | "closed";
+    /** Owning artifact's head id. Null for inline (anonymous) artifacts. */
+    artifact_id: string | null;
+    artifact_version_id: string;
+    artifact_version: number;
+    /** Count of active (non-revoked) human participants. The full participant
+     *  array is intentionally NOT inlined here — agents with many sessions
+     *  would pay the bandwidth on every list call. Fetch
+     *  `GET /v1/sessions/:id/participants` when you need the rows. */
+    active_human_participants: number;
+    created_at: string;
+    expires_at: string;
+    /** Whether the session has a webhook callback configured (URL is NOT
+     *  returned — it may carry a secret in the path). */
+    has_callback: boolean;
+}
+/** Response from GET /v1/sessions/:id/participants — every participant on
+ *  one session (active and revoked). Bounded by MAX_PARTICIPANTS_PER_SESSION
+ *  on the relay so no pagination is needed. */
+export interface ParticipantsList {
+    session_id: string;
+    items: ParticipantSummary[];
+}
+/** Response from GET /v1/sessions. */
+export interface SessionsPage {
+    items: SessionSummary[];
+    /** Opaque cursor for the next page; null when no more rows. */
+    next_cursor: string | null;
+}
+/** Response from POST /v1/sessions/:id/participants — one-shot, includes the
+ *  plaintext token exactly once. The relay stores only the hash. */
+export interface MintParticipantResponse {
+    participant_id: string;
+    kind: "human";
+    /** The plaintext participant token. Returned ONCE — not recoverable. */
+    token: string;
+    /** The shareable human URL containing the token. */
+    url: string;
+    created_at: string;
+}
 /** One immutable version of an artifact's content. */
 export interface ArtifactVersion {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paneui/core",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Pane relay client: typed HTTP + WebSocket operations against a Pane relay. Framework-free.",
   "license": "MIT",
   "type": "module",
@@ -47,12 +47,12 @@
   },
   "dependencies": {
     "ws": "^8.20.1",
-    "zod": "^3.23.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^22.7.0",
+    "@types/node": "^25.9.1",
     "@types/ws": "^8.18.1",
-    "typescript": "^5.6.0",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.6"
   }
 }