summer-engine 3.7.0 → 4.0.0

package/dist/core/capabilities/apps.d.ts

@@ -0,0 +1,341 @@
+import { z } from "zod";
+/**
+ * Summer Apps (summer_app_*): tools a game team uses inside Summer Studio,
+ * built by agents. Every cloud tool here calls the Summer web API under
+ * /api/mcp/apps with the signed-in Summer account; summer_app_dock asks the
+ * running editor to dock an app (engine ops OpenAppDock / CloseAppDock /
+ * ListAppDocks).
+ *
+ * One implementation for both faces: the MCP tools (src/mcp/tools/app-tools.ts)
+ * and `summer tool app-*` (tool-dispatch.ts) share the schemas and functions
+ * here and pass their own client surface.
+ */
+export declare const APPS_ENDPOINT = "/api/mcp/apps";
+/** The server's long-poll ceiling for summer_app_events. */
+export declare const MAX_APP_EVENTS_WAIT_SECONDS = 50;
+export declare const APP_GUIDE_SECTIONS: readonly ["all", "overview", "manifest", "sdk", "kit", "layout", "design", "examples", "types"];
+export declare const APP_DOCK_SLOTS: readonly ["left", "right", "bottom"];
+export declare const appGuideArgsSchema: z.ZodObject<{
+    section: z.ZodDefault<z.ZodEnum<["all", "overview", "manifest", "sdk", "kit", "layout", "design", "examples", "types"]>>;
+}, "strip", z.ZodTypeAny, {
+    section: "all" | "kit" | "layout" | "examples" | "manifest" | "overview" | "sdk" | "design" | "types";
+}, {
+    section?: "all" | "kit" | "layout" | "examples" | "manifest" | "overview" | "sdk" | "design" | "types" | undefined;
+}>;
+export declare const appListArgsSchema: z.ZodObject<{
+    workspaceId: z.ZodOptional<z.ZodString>;
+    q: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    workspaceId?: string | undefined;
+    q?: string | undefined;
+}, {
+    workspaceId?: string | undefined;
+    q?: string | undefined;
+}>;
+export declare const appCreateArgsSchema: z.ZodObject<{
+    name: z.ZodString;
+    purpose: z.ZodOptional<z.ZodString>;
+    format: z.ZodDefault<z.ZodEnum<["code", "layout"]>>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    folder: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    format: "code" | "layout";
+    folder?: string | undefined;
+    workspaceId?: string | undefined;
+    purpose?: string | undefined;
+}, {
+    name: string;
+    format?: "code" | "layout" | undefined;
+    folder?: string | undefined;
+    workspaceId?: string | undefined;
+    purpose?: string | undefined;
+}>;
+export declare const appPublishArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    dir: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        content: z.ZodString;
+        encoding: z.ZodDefault<z.ZodEnum<["utf8", "base64"]>>;
+    }, "strip", z.ZodTypeAny, {
+        encoding: "utf8" | "base64";
+        path: string;
+        content: string;
+    }, {
+        path: string;
+        content: string;
+        encoding?: "utf8" | "base64" | undefined;
+    }>, "many">>;
+    layout: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    manifest: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    note: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    manifest: Record<string, unknown>;
+    appId: string;
+    note?: string | undefined;
+    files?: {
+        encoding: "utf8" | "base64";
+        path: string;
+        content: string;
+    }[] | undefined;
+    idempotencyKey?: string | undefined;
+    dir?: string | undefined;
+    layout?: Record<string, unknown> | undefined;
+}, {
+    manifest: Record<string, unknown>;
+    appId: string;
+    note?: string | undefined;
+    files?: {
+        path: string;
+        content: string;
+        encoding?: "utf8" | "base64" | undefined;
+    }[] | undefined;
+    idempotencyKey?: string | undefined;
+    dir?: string | undefined;
+    layout?: Record<string, unknown> | undefined;
+}>;
+export declare const appGetArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+}, {
+    appId: string;
+}>;
+export declare const appEventsArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    after: z.ZodDefault<z.ZodNumber>;
+    timeoutSeconds: z.ZodDefault<z.ZodNumber>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodEnum<["agent", "error", "feedback", "tool"]>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    timeoutSeconds: number;
+    after: number;
+    appId: string;
+    kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
+}, {
+    appId: string;
+    kinds?: ("error" | "agent" | "tool" | "feedback")[] | undefined;
+    timeoutSeconds?: number | undefined;
+    after?: number | undefined;
+}>;
+export declare const appPageArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    fill: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        value: z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    }, "strip", z.ZodTypeAny, {
+        value: string | number | boolean;
+        field: string;
+    }, {
+        value: string | number | boolean;
+        field: string;
+    }>, "many">>;
+    press: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+    fill?: {
+        value: string | number | boolean;
+        field: string;
+    }[] | undefined;
+    press?: string | undefined;
+}, {
+    appId: string;
+    fill?: {
+        value: string | number | boolean;
+        field: string;
+    }[] | undefined;
+    press?: string | undefined;
+}>;
+export declare const appUpdateArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    purpose: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["scratch", "kept", "archived"]>>;
+    folder: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+    name?: string | undefined;
+    status?: "scratch" | "kept" | "archived" | undefined;
+    folder?: string | null | undefined;
+    purpose?: string | undefined;
+}, {
+    appId: string;
+    name?: string | undefined;
+    status?: "scratch" | "kept" | "archived" | undefined;
+    folder?: string | null | undefined;
+    purpose?: string | undefined;
+}>;
+export declare const appScreenshotArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+    theme: z.ZodDefault<z.ZodEnum<["light", "dark"]>>;
+    fullPage: z.ZodDefault<z.ZodBoolean>;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    steps: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        click: z.ZodOptional<z.ZodString>;
+        press: z.ZodOptional<z.ZodString>;
+        wait: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }, {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }>, "many">>;
+    out: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    width: number;
+    height: number;
+    theme: "light" | "dark";
+    appId: string;
+    fullPage: boolean;
+    version?: number | undefined;
+    params?: Record<string, string> | undefined;
+    out?: string | undefined;
+    steps?: {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }[] | undefined;
+}, {
+    appId: string;
+    version?: number | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    params?: Record<string, string> | undefined;
+    out?: string | undefined;
+    theme?: "light" | "dark" | undefined;
+    steps?: {
+        wait?: number | undefined;
+        press?: string | undefined;
+        click?: string | undefined;
+    }[] | undefined;
+    fullPage?: boolean | undefined;
+}>;
+export declare const appDataArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    collection: z.ZodOptional<z.ZodString>;
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    ops: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">>;
+    as: z.ZodOptional<z.ZodEnum<["agent", "seed"]>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    appId: string;
+    ops?: Record<string, unknown>[] | undefined;
+    after?: string | undefined;
+    as?: "seed" | "agent" | undefined;
+    collection?: string | undefined;
+}, {
+    appId: string;
+    ops?: Record<string, unknown>[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    as?: "seed" | "agent" | undefined;
+    collection?: string | undefined;
+}>;
+export declare const appToolsArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    appId: string;
+}, {
+    appId: string;
+}>;
+export declare const appCallArgsSchema: z.ZodObject<{
+    appId: z.ZodString;
+    tool: z.ZodString;
+    input: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    input: Record<string, unknown>;
+    tool: string;
+    appId: string;
+}, {
+    tool: string;
+    appId: string;
+    input?: Record<string, unknown> | undefined;
+}>;
+export declare const appReportGapArgsSchema: z.ZodObject<{
+    capability: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    method: z.ZodOptional<z.ZodString>;
+    appId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    capability: string;
+    method?: string | undefined;
+    detail?: string | undefined;
+    appId?: string | undefined;
+}, {
+    capability: string;
+    method?: string | undefined;
+    detail?: string | undefined;
+    appId?: string | undefined;
+}>;
+export declare const appDockArgsSchema: z.ZodObject<{
+    action: z.ZodDefault<z.ZodEnum<["open", "close", "list"]>>;
+    appId: z.ZodOptional<z.ZodString>;
+    slot: z.ZodDefault<z.ZodEnum<["left", "right", "bottom"]>>;
+}, "strip", z.ZodTypeAny, {
+    action: "close" | "open" | "list";
+    slot: "left" | "right" | "bottom";
+    appId?: string | undefined;
+}, {
+    action?: "close" | "open" | "list" | undefined;
+    appId?: string | undefined;
+    slot?: "left" | "right" | "bottom" | undefined;
+}>;
+export interface AppsReply {
+    ok: boolean;
+    status: number;
+    data: Record<string, unknown>;
+}
+export interface AppsDeps {
+    request(method: "GET" | "POST", endpoint: string, init: {
+        query?: URLSearchParams;
+        body?: unknown;
+        timeoutMs: number;
+    }): Promise<AppsReply>;
+    readDir?: (dir: string) => Promise<Array<{
+        path: string;
+        content: string;
+        encoding: "utf8" | "base64";
+    }>>;
+}
+/** Fetch with the Summer account token; errors come back as replies, never throws. */
+export declare function appsGateway(surface: "mcp" | "cli", tool: string): AppsDeps["request"];
+export declare function appGuide(args: z.output<typeof appGuideArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appList(args: z.output<typeof appListArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appCreate(args: z.output<typeof appCreateArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+/** Every file under dir (dotfiles, node_modules and .d.ts type files skipped), as publish files. */
+export declare function readAppDir(dir: string): Promise<Array<{
+    path: string;
+    content: string;
+    encoding: "utf8" | "base64";
+}>>;
+export declare function appPublish(args: z.output<typeof appPublishArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appGet(args: z.output<typeof appGetArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appEvents(args: z.output<typeof appEventsArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appPage(args: z.output<typeof appPageArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appUpdate(args: z.output<typeof appUpdateArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+/**
+ * summer_app_screenshot: the server renders the app headless and read-only as the
+ * person and answers the PNG (base64) with its console, errors and declared page.
+ * The image moves to `image`; `out` also writes it to disk.
+ */
+export declare function appScreenshot(args: z.output<typeof appScreenshotArgsSchema>, deps: AppsDeps & {
+    writeFile?: (file: string, data: Buffer) => Promise<void>;
+}): Promise<Record<string, unknown>>;
+export declare function appData(args: z.output<typeof appDataArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appTools(args: z.output<typeof appToolsArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appCall(args: z.output<typeof appCallArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare function appReportGap(args: z.output<typeof appReportGapArgsSchema>, deps: AppsDeps): Promise<Record<string, unknown>>;
+export declare const APP_DOCK_FALLBACK = "This engine build cannot dock apps yet. Open the app in the Summer Studio tab instead (summer_studio_open with /studio/apps/<appId>), or update Summer Engine.";
+/** The engine op for one dock action. */
+export declare function appDockOp(args: z.output<typeof appDockArgsSchema>): {
+    op: string;
+    [key: string]: unknown;
+};