esoul-sdk 0.7.0 → 0.16.0

package/dist/files.js

@@ -9,6 +9,7 @@
  * provider-opaque `ref`; labels are display only. A source that cannot
  * answer reports `source_unavailable` — never an empty listing.
  */
+/** A files call refused — `kind` says why: not_declared (the manifest has no `files` grant for it), source_unavailable, not_found, too_large, read_only, disabled, bad_ref. */
 export class FileSourceError extends Error {
     kind;
     constructor(kind, message) {
@@ -17,8 +18,11 @@ export class FileSourceError extends Error {
         this.kind = kind;
     }
 }
+/** The default most `FilesApi.read` returns (25 MB); pass `capBytes` to raise it. */
 export const FILE_READ_CAP_BYTES = 25 * 1024 * 1024;
+/** The ceiling `capBytes` may raise a read to (100 MB). */
 export const FILE_READ_HARD_CAP_BYTES = 100 * 1024 * 1024;
+/** A file source id as its parts: the workspace, Google Drive, a local mount, or an app's own provider. */
 export function parseSourceId(sourceId) {
     if (sourceId === "workspace")
         return { kind: "workspace" };
@@ -37,3 +41,47 @@ export function parseSourceId(sourceId) {
     }
     return { kind: "plugin", providerKey: head, connectionId: tail };
 }
+/** The most one page of a listing holds. */
+export const FILE_LIST_PAGE_MAX = 1000;
+/** The most `listAll` gathers before it answers `truncated: true`. */
+export const FILE_LIST_ALL_MAX = 20_000;
+/** The most `readMany` reads in one call, in files and in bytes. */
+export const FILE_READ_MANY_MAX = 200;
+/** …and the most bytes it gathers in one call (64 MB); past it the remaining rows answer `too_large`. */
+export const FILE_READ_MANY_TOTAL_BYTES = 64 * 1024 * 1024;
+/** The longest a read grant lives (24 h); the default is one hour. */
+export const FILE_GRANT_MAX_TTL_SECONDS = 24 * 60 * 60;
+/** How long a read grant lives when `ttlSeconds` is not given: one hour. */
+export const FILE_GRANT_DEFAULT_TTL_SECONDS = 60 * 60;
+/** The URL of one file under a grant. `width` asks for a downsized image (a thumbnail), 16–2048 px. */
+export function fileGrantUrl(grant, ref, opts) {
+    const id = typeof ref === "string" ? ref : ref.ref;
+    const w = opts?.width ? Math.max(16, Math.min(2048, Math.round(opts.width))) : 0;
+    return `${grant.urlBase}&ref=${encodeURIComponent(id)}${w ? `&w=${w}` : ""}`;
+}
+/** Does an entry pass these listing options? The one rule every provider's listing is held to. */
+export function matchesListOptions(entry, opts) {
+    if (!opts)
+        return true;
+    if (opts.only && entry.kind !== opts.only)
+        return false;
+    if (opts.nameContains && !entry.name.toLowerCase().includes(opts.nameContains.toLowerCase()))
+        return false;
+    return true;
+}
+/** `pageSize` as a provider may use it: a whole number from 1 to FILE_LIST_PAGE_MAX, default 100. */
+export function listPageSize(opts) {
+    const n = Math.floor(Number(opts?.pageSize));
+    return Number.isFinite(n) && n >= 1 ? Math.min(n, FILE_LIST_PAGE_MAX) : 100;
+}
+/** "sheets/quality_dataset/Type5" → its segments. Leading "/", a source's own label and empty parts are dropped. */
+export function splitFilePath(path) {
+    return String(path ?? "")
+        .split("/")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0 && s !== ".");
+}
+/** Natural name order: "frame_2" before "frame_10". */
+export function compareFileNames(a, b) {
+    return a.localeCompare(b, undefined, { numeric: true, sensitivity: "base" });
+}

package/dist/helpers.d.ts

@@ -13,6 +13,10 @@ export interface RequiredStateShape {
     /** Keys that must be non-null objects. */
     maps?: Record<string, unknown>;
 }
+/**
+ * The genesis-seeded keys a state lacks — for `getStateDescription`: a MISSING list means the state
+ * did not load (say so), an EMPTY one is real. Never floor an absent key to `[]`.
+ */
 export declare function missingStateKeys(shape: RequiredStateShape): string[];
 /**
  * `null` when the state is whole — the describer proceeds normally.
@@ -56,6 +60,12 @@ export declare function currentShareId(): string | null;
  * outside a preview: the platform never reads it, and the header is not sent.
  */
 export declare function previewPersona(): string | null;
+/**
+ * Call one of your app's server ops from the UI or a tool: POSTs `{nodeId, args}` to the op's route
+ * (the installed app's `/api/plugins/<id>/op/<op>`, or the Forge preview's own route) with the
+ * session, the share and the VIEW AS persona the page carries, and returns the op's result — or
+ * throws the op's refusal with its code.
+ */
 export declare function callPluginOp<T = unknown>(pluginId: string, op: string, nodeId: string, args?: unknown): Promise<T>;
 /**
  * What a failed op call throws. It CARRIES the platform's refusal code, so a

package/dist/helpers.js

@@ -20,6 +20,10 @@ export function deterministicReducerId(prefix, seed) {
         h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
     return `${prefix}_${h.toString(36)}${(s.length & 0xffff).toString(36)}`;
 }
+/**
+ * The genesis-seeded keys a state lacks — for `getStateDescription`: a MISSING list means the state
+ * did not load (say so), an EMPTY one is real. Never floor an absent key to `[]`.
+ */
 export function missingStateKeys(shape) {
     const missing = [];
     for (const [key, value] of Object.entries(shape.lists ?? {})) {
@@ -102,6 +106,12 @@ function previewViewerHeaders() {
     const p = previewPersona();
     return p ? { [PREVIEW_VIEWER_HEADER]: p } : {};
 }
+/**
+ * Call one of your app's server ops from the UI or a tool: POSTs `{nodeId, args}` to the op's route
+ * (the installed app's `/api/plugins/<id>/op/<op>`, or the Forge preview's own route) with the
+ * session, the share and the VIEW AS persona the page carries, and returns the op's result — or
+ * throws the op's refusal with its code.
+ */
 export async function callPluginOp(pluginId, op, nodeId, args) {
     const onServer = typeof window === "undefined";
     const serverBase = onServer ? process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000" : "";

package/dist/index.d.ts

@@ -2,11 +2,32 @@ export * from "./types.js";
 export * from "./manifest.js";
 export * from "./helpers.js";
 export * from "./files.js";
+export * from "./assets.js";
+export * from "./labelme.js";
 export * from "./bindings.js";
 /** WHO hears a realtime message (S8): topic audiences, and who may aim one. */
 export * from "./audience.js";
 /** The app's own words for the platform's kinds of caller (S3). */
 export * from "./roles.js";
+/**
+ * One declaration per op: `defineOps` in a shared file, `handleOp` in server.ts,
+ * `opTool` in app.tsx — a tool's parameters cannot drift from what its op takes.
+ */
+export * from "./ops.js";
+/** A chart from data — one SVG for the app's screen and, rendered, for a tool's answer. */
+export * from "./chart.js";
+/**
+ * Editor sync: how a mounted editor takes a change from another device or an agent while the person types —
+ * the decision and the merges (records by id, fields, lines). The hook is `useRemoteReconcile` in esoul-sdk/react.
+ */
+export * from "./editor-sync.js";
+/**
+ * The agent tool for one op, declared once: `opTool(ops.play, { say })` in app.tsx gives a tool whose
+ * parameters ARE the op's zod input and whose call goes to `callPluginOp` — as the acting viewer on
+ * the platform, over the preview's own route in a Forge box. `say` turns the op's result into the
+ * words the model reads.
+ */
+export declare const opTool: <T extends import("./ops.js").OpInputs, K extends keyof T & string, R = unknown>(ops: T, name: K, cfg: import("./ops.js").OpToolConfig<T[K], R>) => import("./ops.js").DerivedTool;
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
 /**
@@ -28,3 +49,6 @@ export declare function definePluginChannel<T extends Record<string, {
 }) & {
     topicNames: (keyof T & string)[];
 };
+/** Roles the owner composes (docs/13): the pure compiler, for tests and for a screen that previews a definition. */
+export { compileCustomRole, compileEnvelope, CustomRoleError, coerceAttr, coerceAttrs, attrProblem, ATTR_TYPES } from "./db/custom-roles.js";
+export type { CompiledCustomRole, CustomRoleDefinitionRaw, CustomRoleGrant, CustomRolesEnvelope, CustomRolesEnvelopeRaw, AttrType, AttrValue } from "./db/custom-roles.js";

package/dist/index.js

@@ -2,11 +2,34 @@ export * from "./types.js";
 export * from "./manifest.js";
 export * from "./helpers.js";
 export * from "./files.js";
+export * from "./assets.js";
+export * from "./labelme.js";
 export * from "./bindings.js";
 /** WHO hears a realtime message (S8): topic audiences, and who may aim one. */
 export * from "./audience.js";
 /** The app's own words for the platform's kinds of caller (S3). */
 export * from "./roles.js";
+/**
+ * One declaration per op: `defineOps` in a shared file, `handleOp` in server.ts,
+ * `opTool` in app.tsx — a tool's parameters cannot drift from what its op takes.
+ */
+export * from "./ops.js";
+/** A chart from data — one SVG for the app's screen and, rendered, for a tool's answer. */
+export * from "./chart.js";
+/**
+ * Editor sync: how a mounted editor takes a change from another device or an agent while the person types —
+ * the decision and the merges (records by id, fields, lines). The hook is `useRemoteReconcile` in esoul-sdk/react.
+ */
+export * from "./editor-sync.js";
+import { callPluginOp } from "./helpers.js";
+import { makeOpTool } from "./ops.js";
+/**
+ * The agent tool for one op, declared once: `opTool(ops.play, { say })` in app.tsx gives a tool whose
+ * parameters ARE the op's zod input and whose call goes to `callPluginOp` — as the acting viewer on
+ * the platform, over the preview's own route in a Forge box. `say` turns the op's result into the
+ * words the model reads.
+ */
+export const opTool = makeOpTool(callPluginOp);
 /** Id minting for dataCreators; an app depends on the SDK, not on nanoid. */
 export { nanoid } from "nanoid";
 /**
@@ -26,3 +49,5 @@ export function definePluginChannel(args) {
     factory.topicNames = Object.keys(args.topics);
     return factory;
 }
+/** Roles the owner composes (docs/13): the pure compiler, for tests and for a screen that previews a definition. */
+export { compileCustomRole, compileEnvelope, CustomRoleError, coerceAttr, coerceAttrs, attrProblem, ATTR_TYPES } from "./db/custom-roles.js";

package/dist/labelme.d.ts

@@ -0,0 +1,84 @@
+/**
+ * LabelMe (https://github.com/labelmeai/labelme) label files — pure helpers.
+ *
+ * A label file is `<image stem>.json` BESIDE its image, in the same folder,
+ * with polygon points in ORIGINAL IMAGE PIXELS and `imageData: null` (LabelMe
+ * loads the picture through `imagePath`). That layout is the whole contract
+ * with a training pipeline: it reads the pairs, nothing else.
+ *
+ * `pairImagesWithLabels` is the one place "which images are labelled" is
+ * decided — the grid's green mark, the progress count and the list a machine
+ * downloads for training all read the same answer.
+ */
+import type { FileEntry } from "./files.js";
+export interface LabelPoint {
+    x: number;
+    y: number;
+}
+/** One polygon of a label file, as an app holds it. */
+export interface LabelShape {
+    label: string;
+    points: LabelPoint[];
+    /** LabelMe's `group_id` — ties shapes together (the edges of one column). */
+    groupId?: number | null;
+    description?: string;
+}
+export interface LabelMeShape {
+    label: string;
+    points: [number, number][];
+    group_id: number | null;
+    description: string;
+    shape_type: "polygon";
+    flags: Record<string, never>;
+}
+export interface LabelMeDoc {
+    version: string;
+    flags: Record<string, never>;
+    shapes: LabelMeShape[];
+    imagePath: string;
+    imageData: null;
+    imageHeight: number;
+    imageWidth: number;
+}
+/** The `version` written into a label file — the LabelMe release whose format this is. */
+export declare const LABELME_VERSION = "5.5.0";
+/** The image kinds a labeller opens. */
+export declare const LABEL_IMAGE_EXTS: readonly [".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff"];
+/** `frame_001.JPG` → `frame_001` (the pairing key keeps its case; extensions do not count). */
+export declare function fileStem(name: string): string;
+/** `photo.png` → `photo.json`. */
+export declare function labelFileNameFor(imageName: string): string;
+/** Is this file name an image a labeller opens (`LABEL_IMAGE_EXTS`, any case)? */
+export declare function isLabelImageName(name: string): boolean;
+/** Shapes → a LabelMe document. Polygons under three points are dropped: LabelMe refuses them and so does a trainer. */
+export declare function serializeLabelMe(args: {
+    shapes: LabelShape[];
+    imageName: string;
+    width: number;
+    height: number;
+}): LabelMeDoc;
+/**
+ * A LabelMe document (parsed JSON, or its text) → shapes. Tolerant: anything
+ * that is not a polygon with numeric points is skipped, and garbage answers []
+ * — a bad label file must never take the labeller down. `size` is the image
+ * size the file claims, when it claims one.
+ */
+export declare function parseLabelMe(json: unknown): {
+    shapes: LabelShape[];
+    size: {
+        width: number;
+        height: number;
+    } | null;
+};
+export interface LabelledImage {
+    image: FileEntry;
+    /** The label file beside it, or null — unlabelled. */
+    label: FileEntry | null;
+}
+/**
+ * One folder's listing → its images, each with the label file beside it.
+ * Pairing is by STEM, case-sensitively first (what LabelMe and a trainer do),
+ * then case-insensitively. Two images sharing a stem (`a.jpg`, `a.png`) both
+ * pair with the one `a.json`. Order: natural name order.
+ */
+export declare function pairImagesWithLabels(entries: FileEntry[]): LabelledImage[];

package/dist/labelme.js

@@ -0,0 +1,118 @@
+/** The `version` written into a label file — the LabelMe release whose format this is. */
+export const LABELME_VERSION = "5.5.0";
+/** The image kinds a labeller opens. */
+export const LABEL_IMAGE_EXTS = [".jpg", ".jpeg", ".png", ".bmp", ".webp", ".tif", ".tiff"];
+const round2 = (n) => Math.round(n * 100) / 100;
+/** `frame_001.JPG` → `frame_001` (the pairing key keeps its case; extensions do not count). */
+export function fileStem(name) {
+    const dot = name.lastIndexOf(".");
+    return dot > 0 ? name.slice(0, dot) : name;
+}
+/** `photo.png` → `photo.json`. */
+export function labelFileNameFor(imageName) {
+    return `${fileStem(imageName)}.json`;
+}
+/** Is this file name an image a labeller opens (`LABEL_IMAGE_EXTS`, any case)? */
+export function isLabelImageName(name) {
+    const lower = name.toLowerCase();
+    return LABEL_IMAGE_EXTS.some((e) => lower.endsWith(e));
+}
+/** Shapes → a LabelMe document. Polygons under three points are dropped: LabelMe refuses them and so does a trainer. */
+export function serializeLabelMe(args) {
+    if (!(args.width > 0) || !(args.height > 0))
+        throw new Error("serializeLabelMe needs the image's real width and height — a trainer sizes its label map from them");
+    return {
+        version: LABELME_VERSION,
+        flags: {},
+        shapes: args.shapes
+            .filter((s) => Array.isArray(s.points) && s.points.length >= 3)
+            .map((s) => ({
+            label: s.label || "object",
+            points: s.points.map((p) => [round2(p.x), round2(p.y)]),
+            group_id: typeof s.groupId === "number" ? s.groupId : null,
+            description: s.description ?? "",
+            shape_type: "polygon",
+            flags: {},
+        })),
+        imagePath: args.imageName,
+        imageData: null,
+        imageHeight: Math.round(args.height),
+        imageWidth: Math.round(args.width),
+    };
+}
+/**
+ * A LabelMe document (parsed JSON, or its text) → shapes. Tolerant: anything
+ * that is not a polygon with numeric points is skipped, and garbage answers []
+ * — a bad label file must never take the labeller down. `size` is the image
+ * size the file claims, when it claims one.
+ */
+export function parseLabelMe(json) {
+    let doc = json;
+    if (typeof json === "string") {
+        try {
+            doc = JSON.parse(json);
+        }
+        catch {
+            return { shapes: [], size: null };
+        }
+    }
+    if (!doc || typeof doc !== "object")
+        return { shapes: [], size: null };
+    const d = doc;
+    const size = typeof d.imageWidth === "number" && typeof d.imageHeight === "number" && d.imageWidth > 0 && d.imageHeight > 0 ? { width: d.imageWidth, height: d.imageHeight } : null;
+    if (!Array.isArray(d.shapes))
+        return { shapes: [], size };
+    const shapes = [];
+    for (const raw of d.shapes) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const sh = raw;
+        if (sh.shape_type && sh.shape_type !== "polygon")
+            continue;
+        if (!Array.isArray(sh.points))
+            continue;
+        const points = [];
+        for (const p of sh.points) {
+            if (Array.isArray(p) && p.length >= 2 && typeof p[0] === "number" && typeof p[1] === "number" && Number.isFinite(p[0]) && Number.isFinite(p[1]))
+                points.push({ x: p[0], y: p[1] });
+        }
+        if (points.length < 3)
+            continue;
+        shapes.push({
+            label: typeof sh.label === "string" && sh.label ? sh.label : "object",
+            points,
+            ...(typeof sh.group_id === "number" ? { groupId: sh.group_id } : {}),
+            ...(typeof sh.description === "string" && sh.description ? { description: sh.description } : {}),
+        });
+    }
+    return { shapes, size };
+}
+/**
+ * One folder's listing → its images, each with the label file beside it.
+ * Pairing is by STEM, case-sensitively first (what LabelMe and a trainer do),
+ * then case-insensitively. Two images sharing a stem (`a.jpg`, `a.png`) both
+ * pair with the one `a.json`. Order: natural name order.
+ */
+export function pairImagesWithLabels(entries) {
+    const exact = new Map();
+    const loose = new Map();
+    for (const e of entries) {
+        if (e.kind !== "file" || !e.name.toLowerCase().endsWith(".json"))
+            continue;
+        const stem = fileStem(e.name);
+        // Drive allows two files of one name; the newest is the one a save replaces.
+        const prior = exact.get(stem);
+        if (!prior || (e.modifiedAt ?? 0) > (prior.modifiedAt ?? 0))
+            exact.set(stem, e);
+        const lp = loose.get(stem.toLowerCase());
+        if (!lp || (e.modifiedAt ?? 0) > (lp.modifiedAt ?? 0))
+            loose.set(stem.toLowerCase(), e);
+    }
+    return entries
+        .filter((e) => e.kind === "file" && isLabelImageName(e.name))
+        .map((image) => {
+        const stem = fileStem(image.name);
+        return { image, label: exact.get(stem) ?? loose.get(stem.toLowerCase()) ?? null };
+    })
+        .sort((a, b) => a.image.name.localeCompare(b.image.name, undefined, { numeric: true, sensitivity: "base" }));
+}