@parlor/agent-ui 0.0.0-stage → 0.2.0

package/dist/server/routes.d.ts

@@ -0,0 +1,11 @@
+import type { H3 } from "h3";
+import type { AgentUi } from "./agent-ui.js";
+export declare const MAX_CLIENT_MESSAGE_BYTES: number;
+export interface AgentUiRouteOptions {
+    readonly basePath: string;
+    readonly agentUi: AgentUi;
+    readonly audience: (request: Request) => string | Promise<string>;
+    readonly clientId: (request: Request) => string | undefined;
+}
+export declare function registerAgentUiRoutes(app: H3, options: AgentUiRouteOptions): void;
+//# sourceMappingURL=routes.d.ts.map

package/dist/server/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/server/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,IAAI,CAAC;AAE7B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,eAAO,MAAM,wBAAwB,QAAa,CAAC;AAEnD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClE,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,CAAC;CAC7D;AAID,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CA6BjF"}

package/dist/server/routes.js

@@ -0,0 +1,38 @@
+import { parseClientMessage } from "./schemas.js";
+export const MAX_CLIENT_MESSAGE_BYTES = 256 * 1024;
+const status = (code) => new Response(null, { status: code });
+export function registerAgentUiRoutes(app, options) {
+    const { basePath, agentUi, audience, clientId } = options;
+    app.post(`${basePath}/ui`, async (event) => {
+        const request = event.req;
+        if (Number(request.headers.get("content-length") ?? 0) > MAX_CLIENT_MESSAGE_BYTES) {
+            return status(413);
+        }
+        const body = await request.text();
+        if (new TextEncoder().encode(body).byteLength > MAX_CLIENT_MESSAGE_BYTES) {
+            return status(413);
+        }
+        const id = clientId(request);
+        if (!id)
+            return status(400);
+        let json;
+        try {
+            json = JSON.parse(body);
+        }
+        catch {
+            return status(400);
+        }
+        const message = parseClientMessage(json);
+        if (!message)
+            return status(400);
+        const receipt = agentUi.receive(id, await audience(request), message);
+        if (!receipt.accepted)
+            return status(404);
+        if (receipt.next === undefined)
+            return status(204);
+        return new Response(receipt.next, {
+            headers: { "content-type": "application/json" },
+        });
+    });
+}
+//# sourceMappingURL=routes.js.map

package/dist/server/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../../src/server/routes.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,GAAG,IAAI,CAAC;AASnD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAEtE,MAAM,UAAU,qBAAqB,CAAC,GAAO,EAAE,OAA4B;IACzE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAE1D,GAAG,CAAC,IAAI,CAAC,GAAG,QAAQ,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QACzC,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC;QAC1B,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,wBAAwB,EAAE,CAAC;YAClF,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,GAAG,wBAAwB,EAAE,CAAC;YACzE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,EAAE;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;QACD,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;YAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACnD,OAAO,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE;YAChC,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { H3 } from \"h3\";\n\nimport type { AgentUi } from \"./agent-ui.js\";\nimport { parseClientMessage } from \"./schemas.js\";\n\nexport const MAX_CLIENT_MESSAGE_BYTES = 256 * 1024;\n\nexport interface AgentUiRouteOptions {\n  readonly basePath: string;\n  readonly agentUi: AgentUi;\n  readonly audience: (request: Request) => string | Promise<string>;\n  readonly clientId: (request: Request) => string | undefined;\n}\n\nconst status = (code: number) => new Response(null, { status: code });\n\nexport function registerAgentUiRoutes(app: H3, options: AgentUiRouteOptions): void {\n  const { basePath, agentUi, audience, clientId } = options;\n\n  app.post(`${basePath}/ui`, async (event) => {\n    const request = event.req;\n    if (Number(request.headers.get(\"content-length\") ?? 0) > MAX_CLIENT_MESSAGE_BYTES) {\n      return status(413);\n    }\n    const body = await request.text();\n    if (new TextEncoder().encode(body).byteLength > MAX_CLIENT_MESSAGE_BYTES) {\n      return status(413);\n    }\n    const id = clientId(request);\n    if (!id) return status(400);\n    let json: unknown;\n    try {\n      json = JSON.parse(body);\n    } catch {\n      return status(400);\n    }\n    const message = parseClientMessage(json);\n    if (!message) return status(400);\n    const receipt = agentUi.receive(id, await audience(request), message);\n    if (!receipt.accepted) return status(404);\n    if (receipt.next === undefined) return status(204);\n    return new Response(receipt.next, {\n      headers: { \"content-type\": \"application/json\" },\n    });\n  });\n}\n"]}

package/dist/server/schemas.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import { type ClientMessage } from "../protocol.js";
+export declare const uiOpInputs: {
+    screen: z.ZodObject<{}, z.core.$strip>;
+    navigate: z.ZodObject<{
+        to: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        search: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        replace: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    set: z.ZodObject<{
+        view: z.ZodString;
+        key: z.ZodOptional<z.ZodString>;
+        value: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>;
+    highlight: z.ZodObject<{
+        view: z.ZodString;
+        key: z.ZodOptional<z.ZodString>;
+        field: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+};
+export declare const clientMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
+    type: z.ZodLiteral<"reply">;
+    id: z.ZodString;
+    ok: z.ZodLiteral<true>;
+    result: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"reply">;
+    id: z.ZodString;
+    ok: z.ZodLiteral<false>;
+    error: z.ZodObject<{
+        code: z.ZodEnum<{
+            ambiguous_client: "ambiguous_client";
+            busy: "busy";
+            internal: "internal";
+            invalid_value: "invalid_value";
+            not_mounted: "not_mounted";
+            not_writable: "not_writable";
+            outcome_unknown: "outcome_unknown";
+            timeout: "timeout";
+            unknown_client: "unknown_client";
+            unknown_route: "unknown_route";
+            unsupported_op: "unsupported_op";
+            user_editing: "user_editing";
+        }>;
+        message: z.ZodString;
+        issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            message: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"presence">;
+    focused: z.ZodBoolean;
+    visible: z.ZodBoolean;
+    platform: z.ZodString;
+    buildId: z.ZodOptional<z.ZodString>;
+    ops: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    canConfirm: z.ZodOptional<z.ZodBoolean>;
+    watching: z.ZodCatch<z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodUnknown>, z.ZodTransform<string[], unknown[]>>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"leave">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"answer">;
+    id: z.ZodString;
+    approve: z.ZodBoolean;
+}, z.core.$strip>]>;
+export declare function parseClientMessage(body: unknown): ClientMessage | undefined;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/server/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/server/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,aAAa,EAAuC,MAAM,gBAAgB,CAAC;AAEzF,eAAO,MAAM,UAAU;IACrB,MAAM;IACN,QAAQ;;;;;;IAeR,GAAG;;;;;IAOH,SAAS;;;;;CAQV,CAAC;AAkBF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAyB9B,CAAC;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAG3E"}

package/dist/server/schemas.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { MAX_WATCHED_THREADS, UI_ERROR_CODES } from "../protocol.js";
+export const uiOpInputs = {
+    screen: z.object({}),
+    navigate: z.object({
+        to: z.string(),
+        params: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Values for the $params in the path, e.g. { "taskId": "..." }.'),
+        search: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Search params for the page, as its entry in the list names them."),
+        replace: z
+            .boolean()
+            .optional()
+            .describe("Replace the current history entry instead of pushing one."),
+    }),
+    set: z.object({
+        view: z.string().describe("A writable view's name, as listed."),
+        key: z.string().optional().describe("The item's key, for a keyed view."),
+        value: z
+            .record(z.string(), z.unknown())
+            .describe("The fields to write; others keep their current value."),
+    }),
+    highlight: z.object({
+        view: z.string().describe("A view's name, as ui_screen reports it."),
+        key: z.string().optional().describe("The item's key, for a keyed view."),
+        field: z
+            .string()
+            .optional()
+            .describe("A field inside the view to focus, by its input name."),
+    }),
+};
+const errorSchema = z.object({
+    code: z.enum(UI_ERROR_CODES),
+    message: z.string(),
+    issues: z.array(z.object({ path: z.string(), message: z.string() })).optional(),
+});
+const watchingSchema = z
+    .array(z.unknown())
+    .transform((ids) => ids
+    .filter((id) => typeof id === "string" && id !== "")
+    .slice(0, MAX_WATCHED_THREADS))
+    .optional()
+    .catch(undefined);
+export const clientMessageSchema = z.union([
+    z.object({
+        type: z.literal("reply"),
+        id: z.string().min(1),
+        ok: z.literal(true),
+        result: z.unknown(),
+    }),
+    z.object({
+        type: z.literal("reply"),
+        id: z.string().min(1),
+        ok: z.literal(false),
+        error: errorSchema,
+    }),
+    z.object({
+        type: z.literal("presence"),
+        focused: z.boolean(),
+        visible: z.boolean(),
+        platform: z.string(),
+        buildId: z.string().optional(),
+        ops: z.array(z.string()).optional(),
+        canConfirm: z.boolean().optional(),
+        watching: watchingSchema,
+    }),
+    z.object({ type: z.literal("leave") }),
+    z.object({ type: z.literal("answer"), id: z.string().min(1), approve: z.boolean() }),
+]);
+export function parseClientMessage(body) {
+    const parsed = clientMessageSchema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=schemas.js.map

package/dist/server/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/server/schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\n\nimport { type ClientMessage, MAX_WATCHED_THREADS, UI_ERROR_CODES } from \"../protocol.js\";\n\nexport const uiOpInputs = {\n  screen: z.object({}),\n  navigate: z.object({\n    to: z.string(),\n    params: z\n      .record(z.string(), z.string())\n      .optional()\n      .describe('Values for the $params in the path, e.g. { \"taskId\": \"...\" }.'),\n    search: z\n      .record(z.string(), z.unknown())\n      .optional()\n      .describe(\"Search params for the page, as its entry in the list names them.\"),\n    replace: z\n      .boolean()\n      .optional()\n      .describe(\"Replace the current history entry instead of pushing one.\"),\n  }),\n  set: z.object({\n    view: z.string().describe(\"A writable view's name, as listed.\"),\n    key: z.string().optional().describe(\"The item's key, for a keyed view.\"),\n    value: z\n      .record(z.string(), z.unknown())\n      .describe(\"The fields to write; others keep their current value.\"),\n  }),\n  highlight: z.object({\n    view: z.string().describe(\"A view's name, as ui_screen reports it.\"),\n    key: z.string().optional().describe(\"The item's key, for a keyed view.\"),\n    field: z\n      .string()\n      .optional()\n      .describe(\"A field inside the view to focus, by its input name.\"),\n  }),\n};\n\nconst errorSchema = z.object({\n  code: z.enum(UI_ERROR_CODES),\n  message: z.string(),\n  issues: z.array(z.object({ path: z.string(), message: z.string() })).optional(),\n});\n\nconst watchingSchema = z\n  .array(z.unknown())\n  .transform((ids) =>\n    ids\n      .filter((id): id is string => typeof id === \"string\" && id !== \"\")\n      .slice(0, MAX_WATCHED_THREADS),\n  )\n  .optional()\n  .catch(undefined);\n\nexport const clientMessageSchema = z.union([\n  z.object({\n    type: z.literal(\"reply\"),\n    id: z.string().min(1),\n    ok: z.literal(true),\n    result: z.unknown(),\n  }),\n  z.object({\n    type: z.literal(\"reply\"),\n    id: z.string().min(1),\n    ok: z.literal(false),\n    error: errorSchema,\n  }),\n  z.object({\n    type: z.literal(\"presence\"),\n    focused: z.boolean(),\n    visible: z.boolean(),\n    platform: z.string(),\n    buildId: z.string().optional(),\n    ops: z.array(z.string()).optional(),\n    canConfirm: z.boolean().optional(),\n    watching: watchingSchema,\n  }),\n  z.object({ type: z.literal(\"leave\") }),\n  z.object({ type: z.literal(\"answer\"), id: z.string().min(1), approve: z.boolean() }),\n]);\n\nexport function parseClientMessage(body: unknown): ClientMessage | undefined {\n  const parsed = clientMessageSchema.safeParse(body);\n  return parsed.success ? parsed.data : undefined;\n}\n"]}

package/dist/server/tools.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { type UiManifest } from "../manifest.js";
+import { type AgentOrigin, type ClientSummary, type ScreenSnapshot, type UiOp, type UiOpResults } from "../protocol.js";
+import { type UiBroker } from "./broker.js";
+import type { ClientDirectory } from "./directory.js";
+export type UiToolName = `ui_${UiOp}`;
+export declare const UI_TOOLS: readonly UiToolName[];
+export declare const UI_MANIFEST_RESOURCE = "parlor://manifest";
+export interface AgentToolContext {
+    readonly scope: string;
+    readonly clientId?: string | undefined;
+    readonly origin: AgentOrigin;
+    readonly signal?: AbortSignal | undefined;
+    readonly webOrigin?: string | undefined;
+}
+export interface AgentTool<I extends z.ZodObject = z.ZodObject> {
+    readonly name: UiToolName;
+    readonly description: string;
+    readonly input: I;
+    readonly readOnly: boolean;
+    run(input: z.output<I>, ctx: AgentToolContext): Promise<unknown>;
+}
+export interface ScreenToolResult extends ScreenSnapshot {
+    readonly client: ClientSummary;
+    readonly otherClients: readonly ClientSummary[];
+    readonly tiedWith?: readonly string[] | undefined;
+}
+export interface NavigateToolResult {
+    readonly client: ClientSummary;
+    readonly screen: ScreenSnapshot;
+}
+export type SetToolResult = UiOpResults["set"] & {
+    readonly client: ClientSummary;
+};
+export type HighlightToolResult = UiOpResults["highlight"] & {
+    readonly client: ClientSummary;
+};
+export interface UnreachableResult {
+    readonly reachable: false;
+    readonly reason: "no_client";
+    readonly href?: string | undefined;
+}
+export interface UiToolDeps {
+    readonly directory: ClientDirectory;
+    readonly broker: UiBroker;
+}
+export declare function createUiTools(deps: UiToolDeps): (manifest: UiManifest | undefined) => readonly AgentTool[];
+export declare function uiInstructions(): string;
+//# sourceMappingURL=tools.d.ts.map

package/dist/server/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/server/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EAEnB,KAAK,IAAI,EACT,KAAK,WAAW,EAEjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,KAAK,QAAQ,EAAa,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAa,MAAM,gBAAgB,CAAC;AAGjE,MAAM,MAAM,UAAU,GAAG,MAAM,IAAI,EAAE,CAAC;AAItC,eAAO,MAAM,QAAQ,EAAE,SAAS,UAAU,EAAyB,CAAC;AAEpE,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,MAAM,WAAW,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS;IAC5D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAC;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG;IAC3D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AA4JD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,GACf,CAAC,QAAQ,EAAE,UAAU,GAAG,SAAS,KAAK,SAAS,SAAS,EAAE,CAmM5D;AAED,wBAAgB,cAAc,IAAI,MAAM,CAavC"}

package/dist/server/tools.js

@@ -0,0 +1,312 @@
+import { z } from "zod";
+import { routeHref, } from "../manifest.js";
+import { UI_OPS, uiOpReadOnly, } from "../protocol.js";
+import { UiFailure } from "./broker.js";
+import { uiOpInputs } from "./schemas.js";
+const toolName = (op) => `ui_${op}`;
+export const UI_TOOLS = UI_OPS.map(toolName);
+export const UI_MANIFEST_RESOURCE = "parlor://manifest";
+const clientIdInput = z
+    .string()
+    .optional()
+    .describe("Target a specific app client by id, as listed in client or otherClients of a ui_screen result. Omit to use the one the user is looking at.");
+const UNREACHABLE = { reachable: false, reason: "no_client" };
+function sentence(text) {
+    const trimmed = text.trim();
+    return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
+}
+function viewCatalog(manifest) {
+    if (!manifest || manifest.views.length === 0)
+        return "";
+    const lines = manifest.views.map((view) => `- ${view.name}${view.keyed ? " (keyed)" : ""}: ${sentence(view.description)}`);
+    return `\n\nViews this app can show:\n${lines.join("\n")}`;
+}
+function typeOf(schema) {
+    if (!schema)
+        return "value";
+    if (Array.isArray(schema.enum))
+        return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+    if ("const" in schema)
+        return JSON.stringify(schema.const);
+    const union = (schema.anyOf ?? schema.oneOf);
+    if (Array.isArray(union))
+        return union.map(typeOf).join(" | ");
+    if (schema.type === "array")
+        return `${typeOf(schema.items)}[]`;
+    return typeof schema.type === "string" ? schema.type : "value";
+}
+/** `filter?: "all" | "done", page?: number`: what a page's search params take. */
+function searchOf(search) {
+    const properties = search?.properties;
+    if (!properties || Object.keys(properties).length === 0)
+        return undefined;
+    const required = new Set(Array.isArray(search?.required) ? search.required : []);
+    return Object.entries(properties)
+        .map(([name, schema]) => `${name}${required.has(name) ? "" : "?"}: ${typeOf(schema)}`)
+        .join(", ");
+}
+function routeCatalog(manifest) {
+    if (!manifest || manifest.routes.length === 0)
+        return "";
+    const lines = manifest.routes.map((route) => {
+        const parts = [`- ${route.path}`];
+        if (route.description)
+            parts.push(` - ${sentence(route.description)}`);
+        const search = searchOf(route.search);
+        if (search)
+            parts.push(` Search: ${search}.`);
+        if (route.views.length > 0)
+            parts.push(` Views: ${route.views.join(", ")}.`);
+        return parts.join("");
+    });
+    return `\n\nPages:\n${lines.join("\n")}`;
+}
+function screenDescription(manifest) {
+    return ([
+        "Read what the user currently sees in the app: the route, the actions feeding the screen (name and input, never data), the views on screen with their values, and attention.",
+        "route is the page the url matched, with notFound: false, its path pattern, params, search and url; when the url matches no page and the app shows its not-found screen, route is notFound: true with only the url.",
+        "attention holds focus (the focused element), selection (the text the user selected and the view holding it; null unless the selection lies inside one view), lastInteracted (the view the user last clicked or focused), lastEntered (the view the user last scrolled into view; null until the user scrolls, since items already on screen when the page renders never count), and focal (the view nearest the middle of the viewport).",
+        "Keyed views list only the items inside the viewport, in screen order, plus an offscreen count.",
+        "The result names the app client it came from and every other open client.",
+        "Returns reachable: false when the app is not open anywhere.",
+    ].join(" ") + viewCatalog(manifest));
+}
+function navigateDescription(manifest) {
+    return ([
+        "Take the user's app to a page, filling $params in the path from params.",
+        "Waits for the page's data to load (up to 1.5 s) and returns the new screen in ui_screen's shape, so its route shows the page the app landed on.",
+        "Returns reachable: false with an href to hand the user when the app is not open.",
+    ].join(" ") + routeCatalog(manifest));
+}
+function writableCatalog(manifest) {
+    const lines = (manifest?.views ?? [])
+        .filter((view) => view.writable.length > 0)
+        .map((view) => `- ${view.name}${view.keyed ? " (keyed)" : ""}: ${sentence(view.description)} Fields: ${view.writable.join(", ")}.`);
+    return lines.length === 0 ? "" : `\n\nForms you can fill:\n${lines.join("\n")}`;
+}
+function setDescription(manifest) {
+    return ([
+        "Fill fields of a form the user sees, as a proposal: the user reviews it and submits it themselves. Call the matching action instead only when the user explicitly asks you to submit.",
+        "value is merged into the view's current value field by field; fields you omit keep what the user typed.",
+        "Returns the view's value read back from the screen and agentFields, the fields that still hold what you wrote; a field missing from agentFields was changed by the user.",
+        "Refuses with not_mounted, not_writable, user_editing (the user is typing in that field: wait or ask), invalid_value (issues name the fields), or ambiguous_client.",
+        "Returns reachable: false when the app is not open.",
+    ].join(" ") + writableCatalog(manifest));
+}
+function highlightDescription() {
+    return [
+        "Point at something on the user's screen: scrolls a view (a keyed item by key) or one field inside it into the middle of the screen, focuses the field (not on a touch screen, where that opens the keyboard), and marks it for two seconds.",
+        "Use it to show the user what you mean or to ask which one they meant.",
+        "Returns shown, the visible fraction after scrolling, or not_mounted when it is not on screen, or reachable: false when the app is not open.",
+        "Refuses with user_editing when the user is typing in another field: wait or ask, and it moves nothing.",
+    ].join(" ");
+}
+function routeEnum(manifest) {
+    const paths = manifest?.routes.map((route) => route.path) ?? [];
+    const [first, ...rest] = paths;
+    return first === undefined ? z.string() : z.enum([first, ...rest]);
+}
+function defineTool(tool) {
+    return tool;
+}
+function withClients(directory, scope, selection, snapshot) {
+    const chosen = selection.target.client;
+    return {
+        client: directory.summary(chosen),
+        otherClients: directory.summaries(scope).filter((c) => c.id !== chosen.id),
+        ...(selection.tied.length > 0 ? { tiedWith: selection.tied.map((c) => c.id) } : {}),
+        ...snapshot,
+    };
+}
+function missingParams(route, params) {
+    const missing = route.params.filter((name) => !params?.[name]);
+    if (missing.length === 0)
+        return;
+    throw new UiFailure({
+        code: "unknown_route",
+        message: `${route.path} needs params: ${missing.join(", ")}.`,
+        issues: missing.map((name) => ({ path: `params.${name}`, message: "Required" })),
+    });
+}
+function hrefFor(href, webOrigin) {
+    return webOrigin ? new URL(href, webOrigin).href : href;
+}
+export function createUiTools(deps) {
+    const { directory, broker } = deps;
+    const refuseTie = (selection) => {
+        if (selection.tied.length === 0)
+            return;
+        const candidates = [selection.target.client, ...selection.tied];
+        throw new UiFailure({
+            code: "ambiguous_client",
+            message: "The user has several app clients open and none stands out. Ask which one, then retry with clientId.",
+            issues: candidates.map((client) => {
+                const summary = directory.summary(client);
+                return {
+                    path: "clientId",
+                    message: `${summary.id} (${summary.platform}, ${summary.focused ? "focused" : "not focused"}, ${summary.visible ? "visible" : "hidden"}, seen ${summary.seenAgoMs} ms ago)`,
+                };
+            }),
+        });
+    };
+    const requireOp = (selection, op) => {
+        const { client } = selection.target;
+        if (client.ops.includes(op))
+            return;
+        throw new UiFailure({
+            code: "unsupported_op",
+            message: `The app client ${client.id} (${client.platform}${client.buildId ? `, build ${client.buildId}` : ""}) is too old for ui_${op}. Ask the user to update the app; ui_screen and ui_navigate still work.`,
+        });
+    };
+    const select = (ctx, clientId) => {
+        if (ctx.clientId !== undefined)
+            return selectBound(ctx, ctx.clientId, clientId);
+        if (clientId !== undefined && !directory.connected(ctx.scope, clientId)) {
+            const connected = directory.summaries(ctx.scope).map((client) => client.id);
+            throw new UiFailure({
+                code: "unknown_client",
+                message: `No app client ${clientId} is connected. Connected clients: ${connected.join(", ") || "none"}.`,
+                issues: connected.map((id) => ({ path: "clientId", message: id })),
+            });
+        }
+        return directory.select(ctx.scope, clientId);
+    };
+    const selectBound = (ctx, bound, requested) => {
+        if (requested !== undefined && requested !== bound) {
+            throw new UiFailure({
+                code: "unknown_client",
+                message: `This chat acts on the app client its prompt came from, not on ${requested}.`,
+            });
+        }
+        if (!directory.connected(ctx.scope, bound)) {
+            throw new UiFailure({
+                code: "unknown_client",
+                message: "The app client this chat was sent from is no longer connected.",
+            });
+        }
+        return directory.select(ctx.scope, bound);
+    };
+    const build = (manifest) => {
+        const screen = defineTool({
+            name: "ui_screen",
+            description: screenDescription(manifest),
+            input: uiOpInputs.screen.extend({ clientId: clientIdInput }),
+            readOnly: uiOpReadOnly.screen,
+            async run({ clientId }, ctx) {
+                const selection = select(ctx, clientId);
+                if (!selection)
+                    return UNREACHABLE;
+                const snapshot = await broker.request(selection.target, "screen", {}, ctx.origin, ctx.signal);
+                return withClients(directory, ctx.scope, selection, snapshot);
+            },
+        });
+        const navigate = defineTool({
+            name: "ui_navigate",
+            description: navigateDescription(manifest),
+            input: uiOpInputs.navigate.extend({
+                to: routeEnum(manifest).describe("The page's route path, exactly as listed."),
+                clientId: clientIdInput,
+            }),
+            readOnly: uiOpReadOnly.navigate,
+            async run({ to, params, search, replace, clientId }, ctx) {
+                const selection = select(ctx, clientId);
+                const route = manifest?.routes.find((entry) => entry.path === to);
+                if (manifest && manifest.routes.length > 0 && !route) {
+                    throw new UiFailure({ code: "unknown_route", message: `No page at ${to}.` });
+                }
+                if (route)
+                    missingParams(route, params);
+                if (!selection) {
+                    const href = routeHref(route ?? { path: to, params: [], views: [] }, params, search);
+                    return { ...UNREACHABLE, href: hrefFor(href, ctx.webOrigin) };
+                }
+                refuseTie(selection);
+                const input = {
+                    to,
+                    ...(params ? { params } : {}),
+                    ...(search ? { search } : {}),
+                    ...(replace === undefined ? {} : { replace }),
+                };
+                const result = await broker.request(selection.target, "navigate", input, ctx.origin, ctx.signal);
+                const navigated = {
+                    client: directory.summary(selection.target.client),
+                    screen: result.screen,
+                };
+                return navigated;
+            },
+        });
+        const set = defineTool({
+            name: toolName("set"),
+            description: setDescription(manifest),
+            input: uiOpInputs.set.extend({ clientId: clientIdInput }),
+            readOnly: uiOpReadOnly.set,
+            async run({ view, key, value, clientId }, ctx) {
+                const selection = select(ctx, clientId);
+                if (!selection)
+                    return UNREACHABLE;
+                refuseTie(selection);
+                requireOp(selection, "set");
+                const result = await broker.request(selection.target, "set", { view, ...(key === undefined ? {} : { key }), value }, ctx.origin, ctx.signal);
+                const written = {
+                    client: directory.summary(selection.target.client),
+                    ...result,
+                };
+                return written;
+            },
+        });
+        const highlight = defineTool({
+            name: toolName("highlight"),
+            description: highlightDescription(),
+            input: uiOpInputs.highlight.extend({ clientId: clientIdInput }),
+            readOnly: uiOpReadOnly.highlight,
+            async run({ view, key, field, clientId }, ctx) {
+                const selection = select(ctx, clientId);
+                if (!selection)
+                    return UNREACHABLE;
+                refuseTie(selection);
+                requireOp(selection, "highlight");
+                const result = await broker.request(selection.target, "highlight", {
+                    view,
+                    ...(key === undefined ? {} : { key }),
+                    ...(field === undefined ? {} : { field }),
+                }, ctx.origin, ctx.signal);
+                const pointed = {
+                    client: directory.summary(selection.target.client),
+                    ...result,
+                };
+                return pointed;
+            },
+        });
+        const byOp = {
+            screen,
+            navigate,
+            set,
+            highlight,
+        };
+        return UI_OPS.map((op) => byOp[op]);
+    };
+    let cachedFor;
+    let cached = build(undefined);
+    return (manifest) => {
+        if (manifest !== cachedFor) {
+            cached = build(manifest);
+            cachedFor = manifest;
+        }
+        return cached;
+    };
+}
+export function uiInstructions() {
+    return [
+        "This app's screen is visible to you through the ui_ tools, next to the app's actions.",
+        'Call ui_screen to see what the user is looking at before acting on words like "this", "that" or "here".',
+        "Resolve them from attention in this order: focus, selection, lastInteracted, focal.",
+        "A keyed view's key is the entity id that the app's actions take, so pass it straight to the action.",
+        "Do the work through actions; the screen updates by itself.",
+        "To show the user a page, call ui_navigate with a path from its list.",
+        "You fill forms and the user submits them: use ui_set to fill a form, and call the action that submits it only when the user explicitly asks you to.",
+        "Some actions ask the user to approve them in the app before they run: call them as usual and wait. If one fails with declined, do not retry unless the user asks again; if it fails with confirmation_unavailable, ask the user to do it in the app themselves.",
+        "Use ui_highlight to point at what you mean, or at candidates when you need the user to pick one.",
+        "If a ui_ tool returns reachable: false, the app is not open: tell the user, and for navigation hand them the href.",
+    ].join("\n");
+}
+//# sourceMappingURL=tools.js.map