@unfenced-ai/sdk 0.1.0

package/dist/sessions.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The live-session tier: open a page, drive it, read it, close it.
+ *
+ * These are the bodies of the `Unfenced` methods under its `// ---- live
+ * sessions` heading, moved out and re-shaped from methods to functions that
+ * take a `Transport`. `open` and `switchAccount` also take the `client`, because
+ * they hand it to the `Session` they build. `this.request` became `http.request`
+ * and nothing else changed — the request paths, shapes, and comments are as they
+ * were.
+ */
+import { Transport } from "./http.js";
+import { Session } from "./session.js";
+import type { Unfenced } from "./client.js";
+import type { ExtractedDoc } from "./protocol.js";
+import type { Action, ActResult, ActExpectation, AtAction, DownloadInfo, Format, FormField, FormFillResult, OnAction, PageSnapshot, PendingApproval, ProviderSessionReason, ReadPage, SeenPage, SessionInfo } from "./types.js";
+/**
+ * A session id, safe to splice into a path.
+ *
+ * Every call below builds `/session/<id>/...` by interpolation, and the id
+ * reaches the client from whatever asked for it — an MCP tool argument written
+ * by a model, a CLI flag, a caller's own storage. An id carrying `/`, `?`, `#`
+ * or `..` therefore chooses a DIFFERENT route on the worker while looking like
+ * a session that does not exist: `../../permissions` reads the allowlist,
+ * `x?account=other` appends a parameter the caller never passed. Nothing on
+ * this path validated it.
+ *
+ * Deliberately a shape check and not a format check. Ids are 8 hex characters
+ * today (`randomUUID().slice(0, 8)`), but pinning that here would make a
+ * perfectly reasonable change to the generator break every client; what has to
+ * hold is only that the value is ONE path segment. `encodeURIComponent` is
+ * belt to the braces — it would neutralise the traversal on its own, and the
+ * throw is what makes a bad id readable rather than a 404 from the worker.
+ *
+ * Every caller below is `async` so this arrives as a REJECTION. A promise-
+ * returning method that throws synchronously is caught by `await` and missed by
+ * `.catch()`, which is a difference no caller should have to know about.
+ */
+export declare function sessionPath(id: string): string;
+export declare function open(client: Unfenced, http: Transport, url: string, options?: {
+    headless?: boolean;
+    profile?: "ephemeral" | "agent";
+    proxy?: string;
+    account?: string;
+    intent?: "read" | "act";
+    settleMs?: number;
+}): Promise<Session & {
+    providerSession?: ProviderSessionReason;
+    reusedExistingSession?: boolean;
+    navigated?: boolean;
+    note?: string;
+}>;
+export declare function switchAccount(client: Unfenced, http: Transport, sessionId: string, account: string): Promise<{
+    session: Session;
+    restoredSession: boolean;
+    requestedAccount?: string;
+    observedIdentity?: string;
+}>;
+export declare function pendingApprovals(http: Transport): Promise<{
+    interrupts: PendingApproval[];
+    clearAt: string;
+}>;
+export declare function whoami(http: Transport, sessionId: string): Promise<{
+    identity: string | null;
+    source: string | null;
+}>;
+export declare function liveSessions(http: Transport): Promise<SessionInfo[]>;
+export declare function observe(http: Transport, id: string, opts?: {
+    match?: string;
+    maxControls?: number;
+    maxLinks?: number;
+    excerptChars?: number;
+    media?: boolean;
+}): Promise<PageSnapshot>;
+/**
+ * Read the current page and the server's last provider-session continuity
+ * decision. Unlike `observe`, this keeps the small status envelope so a caller
+ * reconnecting after a network interruption can distinguish a carried login
+ * from a session that needs re-authentication.
+ */
+export declare function refresh(http: Transport, id: string, opts?: {
+    match?: string;
+}): Promise<{
+    page: PageSnapshot;
+    providerSession?: ProviderSessionReason;
+}>;
+export declare function read(http: Transport, id: string, opts?: {
+    match?: string;
+    maxControls?: number;
+    maxLinks?: number;
+    excerptChars?: number;
+    media?: boolean;
+}): Promise<ReadPage>;
+export declare function act(http: Transport, id: string, action: Action | OnAction | AtAction, opts?: {
+    acceptDialog?: boolean;
+    dialogText?: string;
+    brief?: boolean;
+    see?: boolean;
+    expect?: ActExpectation;
+}): Promise<ActResult>;
+export declare function extract(http: Transport, id: string, format?: Format, maxWords?: number): Promise<{
+    doc: ExtractedDoc;
+    content: string;
+    url: string;
+    contentTruncated?: boolean;
+    /** Present when something was withheld: how many words the page held. */
+    totalWords?: number;
+}>;
+export declare function screenshot(http: Transport, id: string): Promise<string>;
+export declare function see(http: Transport, id: string, opts?: {
+    links?: boolean;
+    maxMarks?: number;
+}): Promise<SeenPage>;
+export declare function fill(http: Transport, id: string, fields: readonly FormField[]): Promise<FormFillResult>;
+export declare function park(http: Transport, id: string, minutes?: number, reason?: string): Promise<{
+    ok: boolean;
+    until?: string;
+}>;
+export declare function downloads(http: Transport, id: string): Promise<{
+    downloads: DownloadInfo[];
+}>;
+export declare function readDownload(http: Transport, id: string, filename: string): Promise<{
+    filename: string;
+    bytes: number;
+    content: string;
+    doc: ExtractedDoc;
+}>;
+export declare function closeSession(http: Transport, id: string): Promise<{
+    alreadyClosed?: boolean;
+    wasOpen?: boolean;
+}>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

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

package/dist/sessions.js

@@ -0,0 +1,197 @@
+/**
+ * The live-session tier: open a page, drive it, read it, close it.
+ *
+ * These are the bodies of the `Unfenced` methods under its `// ---- live
+ * sessions` heading, moved out and re-shaped from methods to functions that
+ * take a `Transport`. `open` and `switchAccount` also take the `client`, because
+ * they hand it to the `Session` they build. `this.request` became `http.request`
+ * and nothing else changed — the request paths, shapes, and comments are as they
+ * were.
+ */
+import { UnfencedError } from "./http.js";
+import { Session } from "./session.js";
+/**
+ * A session id, safe to splice into a path.
+ *
+ * Every call below builds `/session/<id>/...` by interpolation, and the id
+ * reaches the client from whatever asked for it — an MCP tool argument written
+ * by a model, a CLI flag, a caller's own storage. An id carrying `/`, `?`, `#`
+ * or `..` therefore chooses a DIFFERENT route on the worker while looking like
+ * a session that does not exist: `../../permissions` reads the allowlist,
+ * `x?account=other` appends a parameter the caller never passed. Nothing on
+ * this path validated it.
+ *
+ * Deliberately a shape check and not a format check. Ids are 8 hex characters
+ * today (`randomUUID().slice(0, 8)`), but pinning that here would make a
+ * perfectly reasonable change to the generator break every client; what has to
+ * hold is only that the value is ONE path segment. `encodeURIComponent` is
+ * belt to the braces — it would neutralise the traversal on its own, and the
+ * throw is what makes a bad id readable rather than a 404 from the worker.
+ *
+ * Every caller below is `async` so this arrives as a REJECTION. A promise-
+ * returning method that throws synchronously is caught by `await` and missed by
+ * `.catch()`, which is a difference no caller should have to know about.
+ */
+export function sessionPath(id) {
+    // A standalone dot segment is normalized by URL parsers even when encoded.
+    // Embedded dots remain valid, but these two values cannot identify a session.
+    if (id === "." || id === ".." || !/^[A-Za-z0-9._~-]{1,128}$/.test(id)) {
+        throw new UnfencedError(400, `not a session id: ${JSON.stringify(id.slice(0, 40))}`, {
+            code: "bad-session-id",
+            remedy: "a session id is the `id` open_page returned - one path segment of letters, digits, dot, dash, underscore or tilde. Open a page and use the id it gives you",
+        });
+    }
+    return encodeURIComponent(id);
+}
+export async function open(client, http, url, options = {}) {
+    const { id, page, providerSession, reusedExistingSession, navigated, note } = await http.request("POST", "/session", { url, ...options });
+    // Attached rather than returned separately, so every existing caller keeps
+    // working unchanged and a caller that wants to know WHY a page opened
+    // without the account's provider session can ask.
+    // Attached the same way `providerSession` is, and for the same reason: the
+    // server has always said when it handed back a page you already had, and
+    // this destructuring is where that sentence used to stop. An agent asking
+    // for a second page on a site got the first one with nothing saying so.
+    return Object.assign(new Session(client, id, page), {
+        providerSession,
+        ...(reusedExistingSession ? { reusedExistingSession, navigated } : {}),
+        // Outside the reuse branch: an ordinary open can carry one too, and it was
+        // being dropped for every caller who had not reused a session.
+        ...(note ? { note } : {}),
+    });
+}
+export async function switchAccount(client, http, sessionId, account) {
+    // `restoredSession` says whether this account had a STORED session to restore. When
+    // false the reopened page is logged out and the resulting identity is whatever a
+    // fresh OAuth resolves — NOT a guarantee it is `account`. `observedIdentity` is who
+    // the page is ACTUALLY signed in as, when the site is one the server can read —
+    // the truth to check against the requested name and across switches.
+    const { id, page, restoredSession, requestedAccount, observedIdentity } = await http.request("POST", `/session/${sessionPath(sessionId)}/switch`, { account });
+    return {
+        session: new Session(client, id, page),
+        restoredSession: Boolean(restoredSession),
+        requestedAccount,
+        observedIdentity,
+    };
+}
+export function pendingApprovals(http) {
+    return http.request("GET", "/interrupts");
+}
+export async function whoami(http, sessionId) {
+    return http.request("GET", `/session/${sessionPath(sessionId)}/whoami`);
+}
+export function liveSessions(http) {
+    return http.request("GET", "/session").then((r) => r.sessions);
+}
+export async function observe(http, id, opts) {
+    return http
+        .request("POST", `/session/${sessionPath(id)}/observe`, opts ?? {})
+        .then((r) => r.page);
+}
+/**
+ * Read the current page and the server's last provider-session continuity
+ * decision. Unlike `observe`, this keeps the small status envelope so a caller
+ * reconnecting after a network interruption can distinguish a carried login
+ * from a session that needs re-authentication.
+ */
+export function refresh(http, id, opts) {
+    return http.request("GET", `/session/${sessionPath(id)}${opts?.match ? `?match=${encodeURIComponent(opts.match)}` : ""}`);
+}
+export async function read(http, id, opts) {
+    return http.request("POST", `/session/${sessionPath(id)}/observe`, opts ?? {});
+}
+export async function act(http, id, action, opts) {
+    // Merged into the body, because the wire is one object — the server reads
+    // `acceptDialog`/`dialogText` off it and hands them to the engine as call
+    // options rather than as part of the action.
+    return http.request("POST", `/session/${sessionPath(id)}/act`, {
+        ...onTheWire(action),
+        ...opts,
+    });
+}
+/**
+ * The one place an action's field names are translated for the wire.
+ *
+ * A multi-select carried its options as an ARRAY under the SINGULAR key —
+ * `{kind:"select", ref, value:["Olive","Caper"]}` — and the server's parser
+ * reads the PLURAL key for arrays: `const many = b["values"]; if
+ * (Array.isArray(many)) …`, falling through otherwise to `String(b["value"])`,
+ * which is `"Olive,Caper"`. That string matches no option on any page, so
+ * multi-select failed on every call and failed in a way that looked like the
+ * site's fault. Reproduced end to end against the two real functions.
+ *
+ * Done HERE rather than in the MCP fold because this function is what writes
+ * the body: every caller — the connector, a typed SDK user, a script — goes
+ * through it, and a fix in one caller leaves the others broken. The action
+ * types keep `value: string | string[]`, which is what the idea actually is;
+ * the wire's two spellings are a wire detail and stop here.
+ */
+function onTheWire(action) {
+    const body = { ...action };
+    if (body["kind"] === "select" && Array.isArray(body["value"])) {
+        body["values"] = body["value"];
+        delete body["value"];
+    }
+    return body;
+}
+export async function extract(http, id, format = "markdown", maxWords) {
+    // `contentTruncated` is on the wire and was not in this type, so every typed
+    // caller lost it: the route sets it when `capExtractInput` cut the DOM at the
+    // 1 MB ceiling, with the comment "a cut page that claims to be whole is worse
+    // than a cut page", and a client that cannot see the field cannot pass it on.
+    //
+    // `maxWords` and `totalWords` are the SECOND ceiling, which had no parameter
+    // and no report: the route defaults to core's 25,000-word budget, so a long
+    // logged-in listing came back cut with `contentTruncated` set for a reason
+    // every description of this call attributed to the megabyte cut instead — and
+    // its only documented remedy, a smaller DOM, does nothing about it.
+    //
+    // Absent means the route's own default, which is what every existing caller
+    // already gets — adding the parameter changed nobody's result, only what a
+    // careful caller is able to ask for.
+    const budget = maxWords === undefined ? "" : `&maxWords=${encodeURIComponent(String(maxWords))}`;
+    return http.request("GET", `/session/${sessionPath(id)}/extract?format=${format}${budget}`);
+}
+export async function screenshot(http, id) {
+    return http
+        .request("GET", `/session/${sessionPath(id)}/screenshot`)
+        .then((r) => r.image);
+}
+export async function see(http, id, opts = {}) {
+    const query = new URLSearchParams({ marks: "1" });
+    if (opts.links)
+        query.set("links", "1");
+    if (opts.maxMarks !== undefined)
+        query.set("maxMarks", String(opts.maxMarks));
+    return http.request("GET", `/session/${sessionPath(id)}/screenshot?${query.toString()}`);
+}
+export async function fill(http, id, fields) {
+    return http.request("POST", `/session/${sessionPath(id)}/fill`, { fields });
+}
+export async function park(http, id, minutes, reason) {
+    return http.request("POST", `/session/${sessionPath(id)}/park`, {
+        ...(minutes !== undefined ? { minutes } : {}),
+        ...(reason !== undefined ? { reason } : {}),
+    });
+}
+export async function downloads(http, id) {
+    return http.request("GET", `/session/${sessionPath(id)}/downloads`);
+}
+export async function readDownload(http, id, filename) {
+    return http.request("GET", `/session/${sessionPath(id)}/downloads/${encodeURIComponent(filename)}`);
+}
+export async function closeSession(http, id) {
+    // The response type has to name every field that is read below, or the
+    // passthrough silently drops it again — which is the whole defect here.
+    return http
+        .request("DELETE", `/session/${sessionPath(id)}`)
+        .then((r) => ({
+        // Passed through rather than rebuilt. This mapped only `alreadyClosed`,
+        // so `wasOpen` — added so a mistyped id stops reading as success — was
+        // dropped here and the MCP tool reported `wasOpen: true` unconditionally.
+        // Its false branch was dead the day it shipped.
+        ...(r.alreadyClosed ? { alreadyClosed: true } : {}),
+        ...(typeof r.wasOpen === "boolean" ? { wasOpen: r.wasOpen } : {}),
+    }));
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

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

package/dist/token-usage.d.ts

@@ -0,0 +1,11 @@
+/** Text returned by a tool/API, not provider-billed model usage. */
+export interface TokenUsage {
+    category: "fetch" | "session" | "other";
+    operation: string;
+    textChars: number;
+    imageCount: number;
+    sessionId?: string;
+}
+/** Count MCP text once; structuredContent duplicates text in our tool replies. */
+export declare function toolTokenUsage(operation: string, input: unknown, result: unknown): TokenUsage;
+//# sourceMappingURL=token-usage.d.ts.map

package/dist/token-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.d.ts","sourceRoot":"","sources":["../src/token-usage.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,UAAU,CA4B7F"}

package/dist/token-usage.js

@@ -0,0 +1,34 @@
+/** Count MCP text once; structuredContent duplicates text in our tool replies. */
+export function toolTokenUsage(operation, input, result) {
+    const args = input;
+    let sessionId = typeof args?.sessionId === "string" ? args.sessionId : undefined;
+    let textChars = 0;
+    let imageCount = 0;
+    const blocks = result?.content;
+    if (Array.isArray(blocks)) {
+        for (const block of blocks) {
+            if (block?.type === "text" && typeof block.text === "string") {
+                textChars += block.text.length;
+                if (!sessionId) {
+                    try {
+                        const payload = JSON.parse(block.text);
+                        if (typeof payload?.sessionId === "string")
+                            sessionId = payload.sessionId;
+                    }
+                    catch {
+                        /* prose is also a valid text block */
+                    }
+                }
+            }
+            else if (block?.type === "image")
+                imageCount++;
+        }
+    }
+    const category = sessionId || operation === "open_page" || operation === "switch_account"
+        ? "session"
+        : /^(fetch_page|fetch_batch|get_page_links)$/.test(operation)
+            ? "fetch"
+            : "other";
+    return { category, operation, textChars, imageCount, ...(sessionId ? { sessionId } : {}) };
+}
+//# sourceMappingURL=token-usage.js.map

package/dist/token-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.js","sourceRoot":"","sources":["../src/token-usage.ts"],"names":[],"mappings":"AASA,kFAAkF;AAClF,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,KAAc,EAAE,MAAe;IAC/E,MAAM,IAAI,GAAG,KAAuC,CAAC;IACrD,IAAI,SAAS,GAAG,OAAO,IAAI,EAAE,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,MAAM,GAAI,MAAuC,EAAE,OAAO,CAAC;IACjE,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,EAAE,IAAI,KAAK,MAAM,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7D,SAAS,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC/B,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,IAAI,CAAC;wBACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;wBAClE,IAAI,OAAO,OAAO,EAAE,SAAS,KAAK,QAAQ;4BAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;oBAC5E,CAAC;oBAAC,MAAM,CAAC;wBACP,sCAAsC;oBACxC,CAAC;gBACH,CAAC;YACH,CAAC;iBAAM,IAAI,KAAK,EAAE,IAAI,KAAK,OAAO;gBAAE,UAAU,EAAE,CAAC;QACnD,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GACZ,SAAS,IAAI,SAAS,KAAK,WAAW,IAAI,SAAS,KAAK,gBAAgB;QACtE,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,2CAA2C,CAAC,IAAI,CAAC,SAAS,CAAC;YAC3D,CAAC,CAAC,OAAO;YACT,CAAC,CAAC,OAAO,CAAC;IAChB,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7F,CAAC"}