@gea-ai/extensions-sdk 0.1.260514-alpha → 0.1.260706-alpha

package/README.md

@@ -5,7 +5,7 @@ Public frontend SDK for GEA extensions.
 ## Install
 
 ```bash
-pnpm add @gea-ai/extensions-sdk zod
+npm install @gea-ai/extensions-sdk
 ```
 
 When testing unpublished SDK changes from this repository, build the SDK and
@@ -13,50 +13,281 @@ link the workspace package from the standalone extension repo:
 
 ```bash
 pnpm --filter @gea-ai/extensions-sdk build
-pnpm add @gea-ai/extensions-sdk@link:/path/to/gea/packages/extensions-sdk
+npm install @gea-ai/extensions-sdk@file:/path/to/gea/packages/extensions-sdk
 ```
 
 ## Minimal Shape
 
 ```tsx
 import {
+  document,
   defineExtension,
-  type ExtensionComponentProps,
+  field,
+  table,
+  wiki,
 } from "@gea-ai/extensions-sdk";
-import { sdk } from "@gea-ai/extensions-sdk/ui";
-import { z } from "zod";
 
-const searchSchema = z.object({}).default({});
+export const extensionDeclaration = defineExtension({
+  frontend: {
+    entry: "src/index.tsx",
+  },
+  name: "Customer Research",
+  resources: {
+    workspace: wiki({
+      children: {
+        notes: table({
+          fields: {
+            note: field.text({
+              indexed: true,
+              required: true,
+              title: "Note",
+            }),
+          },
+          title: "Notes",
+        }),
+        summary: document({
+          initialContent: {
+            format: "markdown",
+            markdown: "# Customer Research Summary\n",
+          },
+          title: "Summary",
+        }),
+      },
+      title: "Customer Research",
+      visibility: "workspace",
+    }),
+  },
+  slug: "customer-research",
+});
+```
+
+```ts
+// src/extension-runtime.ts
+import { createExtensionRuntime } from "@gea-ai/extensions-sdk/react";
+import extensionDeclaration from "../gea.extension";
 
-async function loader() {
-  const resources = await sdk.gea.context.resources.listChildren({
-    path: "/",
+export const { mount, useExtensionApp, useLocale, useTranslations } =
+  createExtensionRuntime({
+    declaration: extensionDeclaration,
   });
+```
 
-  return resources;
-}
+```tsx
+// src/index.tsx
+import { useExtensionApp } from "./extension-runtime";
 
-function ExtensionPage(props: ExtensionComponentProps) {
-  return <pre>{JSON.stringify(props.loaderData, null, 2)}</pre>;
-}
+export default function CustomerResearch() {
+  const app = useExtensionApp();
 
-export const extension = defineExtension({
-  frontend: {
-    component: ExtensionPage,
-    loader,
-    validateSearch: searchSchema,
-  },
-  slug: "customer-research",
-});
+  async function submitNote(note: string) {
+    await app.resources.notes.records.create({
+      note,
+    });
+  }
+
+  return <button onClick={() => void submitNote("Follow up")}>Add</button>;
+}
 ```
 
 Frontend code calls host APIs through SDK helpers. The SDK uses the GEA host
 `postMessage` bridge by default, so extension authors do not need to write
 message plumbing or know the host ORPC transport.
 
-Third-party backend execution is intentionally not part of this V1 SDK. The
-root SDK avoids private monorepo imports so extension projects can type-check
-and build outside the GEA monorepo. Public host context result types are
-exported from `@gea-ai/extensions-sdk/context`. The portable schemas and
-TypeScript types are owned by `@gea-ai/contract` and re-exported by the
-SDK.
+## Actions And Backend Packages
+
+Curated backend-capable extension packages can share one typed action contract
+between frontend and backend code. The frontend calls the host transport, while
+the backend exports handlers that the host loads through ORPC after install,
+membership, and runtime resource checks.
+
+```ts
+// src/contract.ts
+import { defineActions } from "@gea-ai/extensions-sdk/actions";
+import z from "zod";
+
+export const actions = defineActions({
+  ping: {
+    inputSchema: z.object({ value: z.string() }),
+    outputSchema: z.object({ echoed: z.string() }),
+  },
+});
+```
+
+```ts
+// src/backend/index.ts
+import { defineBackendActions } from "@gea-ai/extensions-sdk/backend";
+import { actions } from "../contract";
+
+export const backend = defineBackendActions(actions, {
+  ping: async ({ input }) => ({ echoed: input.value }),
+});
+```
+
+```tsx
+// src/frontend/index.tsx
+import {
+  createExtensionActionClient,
+  type ExtensionActionTransport,
+} from "@gea-ai/extensions-sdk/actions";
+import { actions } from "../contract";
+
+declare const callExtensionAction: ExtensionActionTransport;
+
+const client = createExtensionActionClient({
+  actions,
+  extensionSlug: "example-extension",
+  transport: callExtensionAction,
+});
+
+await client.call("ping", { value: "hello" });
+```
+
+M1 backend actions run through a trusted in-process executor for curated
+marketplace packages. Arbitrary hosted third-party backend execution still
+requires the future sandbox executor; hosted extension uploads reject backend
+declarations for now. Remote marketplace backend files are checked against
+manifest `sha256` and `sizeBytes` metadata before import, and the host dispatches
+only declaration-listed backend actions when the installed manifest declares
+them. The public backend SDK surface is intentionally narrow:
+
+- `sdk.state.records.*` for extension-private workflow state.
+- `sdk.connectors.execute(...)` for host-managed connector calls.
+- `sdk.artifacts.path(...)`, `writeText(...)`, and `writeJson(...)` for
+  extension artifacts.
+- `sdk.resources.records.create/update(...)` and
+  `sdk.resources.documents.update(...)` for declared GEA resources.
+- `sdk.agents.<handle>.run(...)` for declared nested agents.
+
+Any broader host helpers are reserved for internal built-in workflows and are
+not a third-party SDK contract.
+
+`state.records.update({ data })` merges the provided object into the existing
+record data. Use this for partial progress updates; model full replacement as a
+future explicit API if an extension needs it.
+
+Backend actions execute external systems through host-managed connectors:
+
+```ts
+const result = await sdk.connectors.execute({
+  connector: "bocha-search",
+  params: {
+    method: "GET",
+    operation: "request",
+    path: "/search",
+    query: { q: "consumer trend" },
+  },
+});
+```
+
+Connector credentials are resolved by normal GEA connector credential scope
+rules. Extensions should declare every connector dependency in
+`connectorRequirements` so install and setup flows can surface missing
+connectors or credentials before backend actions run. Provider-specific request
+details should live in API, MCP, or native connector implementations; backend
+actions should call those connectors instead of embedding provider credentials or
+direct network integration code.
+
+```ts
+export const extensionDeclaration = defineExtension({
+  // ...
+  connectorRequirements: [
+    {
+      slug: "bocha-search",
+      source: { type: "app_resource", slug: "bocha-search" },
+    },
+    {
+      slug: "wechat-official-account",
+      source: {
+        type: "builtin_connector",
+        slug: "wechat-official-account",
+      },
+    },
+  ],
+});
+```
+
+Installed extension summaries expose each declared connector as `connected`,
+`missing_connector`, or `missing_credentials`. Backend action dispatch preflights
+the same setup state before creating the connector runtime and fails with
+`connector_setup_required` when setup is incomplete.
+
+## Host Context, Theme, And Locale
+
+The local-dev host sends a `host-context` message to the extension iframe on
+load and when the host document theme or locale attributes change. React
+extensions should normally use `createExtensionRuntime` from
+`@gea-ai/extensions-sdk/react`; it wires host-context sync into
+`ExtensionRuntimeProvider` and exposes:
+
+- `useExtensionApp()` for the typed host SDK client and resolved resource
+  handles.
+- `useLocale()` for the current resolved locale.
+- `useTranslations(namespace)` for extension-owned local dictionaries.
+- `mount(Component)` for rendering the default no-props React component into
+  `#root`.
+
+The context includes `locale`, text direction, resolved color scheme, resolved
+theme, and CSS custom properties such as `--background`, `--foreground`, and
+`--border`. The CLI scaffold wires this into `src/extension-runtime.ts`,
+includes a small local i18n dictionary, and configures Tailwind CSS so utilities like
+`bg-background`, `text-foreground`, and `border-border` follow the host theme.
+Extension messages remain extension-owned; the host only supplies the active
+locale.
+
+## Upload And Publish
+
+Use `gea ext package` for local package inspection, then `gea ext deploy` to
+upload the package to the hosted server as an extension app-resource draft.
+Deployment does not publish. Review and publish that app resource from the GEA
+web UI, using the same lifecycle as other app resources.
+
+The app-resource publish version is the canonical hosted version.
+`gea.extension.ts` version metadata is stored in the normalized manifest as package
+metadata. Published extension frontend assets are served by the host through a
+sandboxed iframe asset route, and SDK calls still go through the same
+postMessage bridge.
+
+## Resource Handles
+
+Extensions declare durable resources in `defineExtension`. Draft uploads store
+the normalized declaration only. Publishing and local-dev registration provision
+real GEA resources and bind them to the extension scope. The iframe URL carries
+only extension identity. The host sends `lifecycle.stage = "ready"` plus
+resolved resource handles through the host-context postMessage, and the React
+runtime exposes them as typed `app.resources` when the frontend uses
+`useExtensionApp()` from a runtime created with the declaration.
+
+Use those handles for extension-owned durable data:
+
+```ts
+await app.resources.notes.records.create({
+  note: "Follow up with the design team",
+});
+```
+
+The full demo lives at `examples/research-queue` in the GEA repo. It declares a
+workspace-visible extension wiki, stores submitted URLs in a declared context
+table inside that wiki, declares one aggregate summary document next to the
+table, and starts a hosted agent task with only the resolved table and document
+locations in the prompt.
+
+Third-party iframe extensions should not persist private UI state through
+production `extension_record`. Use browser-local or dev-runtime-local state for
+UI-only state. Durable user-visible data should be modeled as declared GEA
+resources so users and admins can inspect, recover, export, permission, and
+delete it through normal resource flows.
+
+Current table APIs are not yet optimized for large database workloads. Treat
+10k to 100k row scenarios, server-side filtering/sorting, relation joins, and
+benchmarks as a separate table performance track.
+
+The root SDK avoids private monorepo imports so extension projects can
+type-check and build outside the GEA monorepo. Public context resource result
+types are exported from `@gea-ai/extensions-sdk/context`. The portable schemas
+and TypeScript types are owned by `@gea-ai/contract` and re-exported by the SDK.
+
+Local-dev extensions are trusted developer code. They do not declare manifest
+permissions yet. The host bridge exposes only curated SDK methods, but it does
+not enforce extension-specific grants. SDK calls run as the current signed-in
+user and remain constrained by normal hosted ORPC user, workspace, and resource
+permissions.

package/dist/actions.d.ts

@@ -0,0 +1,34 @@
+import { type QueryKey, type UseMutationOptions, type UseQueryOptions } from "@tanstack/react-query";
+import type z from "zod";
+export type ExtensionActionContract<TInput = unknown, TOutput = unknown> = {
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+};
+type AnyExtensionActionContract = ExtensionActionContract<any, any>;
+type ExtensionActionsInput = Record<string, AnyExtensionActionContract>;
+export type ExtensionActionInput<TActions extends ExtensionActionsInput, TAction extends keyof TActions> = TActions[TAction] extends ExtensionActionContract<infer TInput> ? TInput : never;
+export type ExtensionActionOutput<TActions extends ExtensionActionsInput, TAction extends keyof TActions> = TActions[TAction] extends ExtensionActionContract<any, infer TOutput> ? TOutput : never;
+export type ExtensionActionTransport = (input: {
+    action: string;
+    extensionSlug: string;
+    input: unknown;
+}) => Promise<unknown>;
+export declare function defineActions<const TActions extends Record<string, AnyExtensionActionContract>>(actions: TActions): TActions;
+export declare function createExtensionActionClient<const TActions extends ExtensionActionsInput>(input: {
+    actions: TActions;
+    extensionSlug: string;
+    transport: ExtensionActionTransport;
+}): {
+    call: <const TAction extends keyof TActions & string>(action: TAction, inputValue: ExtensionActionInput<TActions, TAction>) => Promise<ExtensionActionOutput<TActions, TAction>>;
+    mutationOptions<const TAction extends keyof TActions & string, TInput extends ExtensionActionInput<TActions, TAction> = ExtensionActionInput<TActions, TAction>, TOutput extends ExtensionActionOutput<TActions, TAction> = ExtensionActionOutput<TActions, TAction>>(action: TAction, options?: Omit<UseMutationOptions<TOutput, Error, TInput, unknown>, "mutationFn" | "mutationKey">): import("@tanstack/react-query").WithRequired<UseMutationOptions<TOutput, Error, TInput, unknown>, "mutationKey">;
+    queryOptions<const TAction extends keyof TActions & string, TInput extends ExtensionActionInput<TActions, TAction> = ExtensionActionInput<TActions, TAction>, TOutput extends ExtensionActionOutput<TActions, TAction> = ExtensionActionOutput<TActions, TAction>>(action: TAction, inputValue: TInput, options?: Omit<UseQueryOptions<TOutput, Error, TOutput, QueryKey>, "queryFn" | "queryKey">): import("@tanstack/react-query").OmitKeyof<UseQueryOptions<TOutput, Error, TOutput, readonly unknown[]>, "queryFn"> & {
+        queryFn?: import("@tanstack/react-query").QueryFunction<TOutput, readonly unknown[], never> | undefined;
+    } & {
+        queryKey: readonly unknown[] & {
+            [dataTagSymbol]: TOutput;
+            [dataTagErrorSymbol]: Error;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAEzB,MAAM,MAAM,uBAAuB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI;IACzE,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC,CAAC;AAEF,KAAK,0BAA0B,GAAG,uBAAuB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAEpE,KAAK,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;AAExE,MAAM,MAAM,oBAAoB,CAC9B,QAAQ,SAAS,qBAAqB,EACtC,OAAO,SAAS,MAAM,QAAQ,IAE9B,QAAQ,CAAC,OAAO,CAAC,SAAS,uBAAuB,CAAC,MAAM,MAAM,CAAC,GAC3D,MAAM,GACN,KAAK,CAAC;AAEZ,MAAM,MAAM,qBAAqB,CAC/B,QAAQ,SAAS,qBAAqB,EACtC,OAAO,SAAS,MAAM,QAAQ,IAE9B,QAAQ,CAAC,OAAO,CAAC,SAAS,uBAAuB,CAAC,GAAG,EAAE,MAAM,OAAO,CAAC,GACjE,OAAO,GACP,KAAK,CAAC;AAEZ,MAAM,MAAM,wBAAwB,GAAG,CAAC,KAAK,EAAE;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,wBAAgB,aAAa,CAC3B,KAAK,CAAC,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,EACjE,OAAO,EAAE,QAAQ,YAElB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,CAAC,QAAQ,SAAS,qBAAqB,EAC5C,KAAK,EAAE;IACP,OAAO,EAAE,QAAQ,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,wBAAwB,CAAC;CACrC;iBAG2B,OAAO,SAAS,MAAM,QAAQ,GAAG,MAAM,UACvD,OAAO,cACH,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,KAClD,OAAO,CAAC,qBAAqB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;0BAe1C,OAAO,SAAS,MAAM,QAAQ,GAAG,MAAM,EAC7C,MAAM,SAAS,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,4CAEtD,OAAO,SAAS,qBAAqB,CAAC,QAAQ,EAAE,OAAO,CAAC,qDAGhD,OAAO,YACL,IAAI,CACZ,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EACnD,YAAY,GAAG,aAAa,CAC7B;uBAiBK,OAAO,SAAS,MAAM,QAAQ,GAAG,MAAM,EAC7C,MAAM,SAAS,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,4CAEtD,OAAO,SAAS,qBAAqB,CAAC,QAAQ,EAAE,OAAO,CAAC,qDAGhD,OAAO,cACH,MAAM,YACR,IAAI,CACZ,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAClD,SAAS,GAAG,UAAU,CACvB;;;;;;;;EAmBN"}

package/dist/actions.js

@@ -0,0 +1,50 @@
+import { mutationOptions as createTanStackMutationOptions, queryOptions as createTanStackQueryOptions, } from "@tanstack/react-query";
+export function defineActions(actions) {
+    return actions;
+}
+export function createExtensionActionClient(input) {
+    const { actions, extensionSlug, transport } = input;
+    async function call(action, inputValue) {
+        const actionContract = actions[action];
+        const parsedInput = actionContract.inputSchema.parse(inputValue);
+        const result = await transport({
+            action,
+            extensionSlug,
+            input: parsedInput,
+        });
+        return actionContract.outputSchema.parse(result);
+    }
+    return {
+        call,
+        mutationOptions(action, options) {
+            const mutationKey = [
+                "extension",
+                extensionSlug,
+                "action",
+                action,
+            ];
+            return createTanStackMutationOptions({
+                ...options,
+                mutationFn: (inputValue) => call(action, inputValue),
+                mutationKey,
+            });
+        },
+        queryOptions(action, inputValue, options) {
+            const actionContract = actions[action];
+            const parsedInput = actionContract.inputSchema.parse(inputValue);
+            const queryKey = [
+                "extension",
+                extensionSlug,
+                "action",
+                action,
+                parsedInput,
+            ];
+            return createTanStackQueryOptions({
+                ...options,
+                queryFn: () => call(action, parsedInput),
+                queryKey,
+            });
+        },
+    };
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,IAAI,6BAA6B,EAChD,YAAY,IAAI,0BAA0B,GAI3C,MAAM,uBAAuB,CAAC;AAkC/B,MAAM,UAAU,aAAa,CAE3B,OAAiB;IACjB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,2BAA2B,CAEzC,KAID;IACC,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAEpD,KAAK,UAAU,IAAI,CACjB,MAAe,EACf,UAAmD;QAEnD,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;YAC7B,MAAM;YACN,aAAa;YACb,KAAK,EAAE,WAAW;SACnB,CAAC,CAAC;QAEH,OAAO,cAAc,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACnD,CAAC;IAED,OAAO;QACL,IAAI;QACJ,eAAe,CAOb,MAAe,EACf,OAGC;YAED,MAAM,WAAW,GAAG;gBAClB,WAAW;gBACX,aAAa;gBACb,QAAQ;gBACR,MAAM;aACqB,CAAC;YAE9B,OAAO,6BAA6B,CAAC;gBACnC,GAAG,OAAO;gBACV,UAAU,EAAE,CAAC,UAAkB,EAAE,EAAE,CACjC,IAAI,CAAC,MAAM,EAAE,UAAU,CAAqB;gBAC9C,WAAW;aACZ,CAAC,CAAC;QACL,CAAC;QACD,YAAY,CAOV,MAAe,EACf,UAAkB,EAClB,OAGC;YAED,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;YACvC,MAAM,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;YACjE,MAAM,QAAQ,GAAG;gBACf,WAAW;gBACX,aAAa;gBACb,QAAQ;gBACR,MAAM;gBACN,WAAW;aACgB,CAAC;YAE9B,OAAO,0BAA0B,CAAC;gBAChC,GAAG,OAAO;gBACV,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAqB;gBAC5D,QAAQ;aACT,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/backend.d.ts

@@ -0,0 +1,159 @@
+import type { ExtensionResolvedResource } from "@gea-ai/contract/extensions";
+import type z from "zod";
+import type { ExtensionActionContract, ExtensionActionInput, ExtensionActionOutput } from "./actions";
+import type { ExtensionDocumentContentInput, ExtensionTableRecord } from "./tables";
+type AnyExtensionActionContract = ExtensionActionContract<any, any>;
+type ExtensionActionsInput = Record<string, AnyExtensionActionContract>;
+export type ExtensionBackendStateRecord<TData extends Record<string, unknown> = Record<string, unknown>> = {
+    createdAt: string;
+    data: TData;
+    id: string;
+    metadata: Record<string, unknown>;
+    ownerId: string | null;
+    recordKey: string;
+    recordType: string;
+    status: string;
+    updatedAt: string;
+};
+export type ExtensionBackendStateRecordsClient = {
+    create<TData extends Record<string, unknown>>(input: {
+        data: TData;
+        metadata?: Record<string, unknown>;
+        ownerId?: string | null;
+        recordKey?: string;
+        recordType: string;
+        status?: string;
+    }): Promise<ExtensionBackendStateRecord<TData>>;
+    get<TData extends Record<string, unknown>>(input: {
+        id: string;
+        recordType: string;
+    }): Promise<ExtensionBackendStateRecord<TData> | null>;
+    list<TData extends Record<string, unknown>>(input: {
+        limit?: number;
+        recordType: string;
+    }): Promise<Array<ExtensionBackendStateRecord<TData>>>;
+    update<TData extends Record<string, unknown>>(input: {
+        data?: Partial<TData>;
+        id: string;
+        metadata?: Record<string, unknown>;
+        status?: string;
+    }): Promise<ExtensionBackendStateRecord<TData>>;
+};
+export type ExtensionBackendArtifactsClient = {
+    path(...segments: string[]): string;
+    readJson<TOutput>(input: {
+        chatId: string;
+        maxCharacters?: number;
+        path: string;
+        schema: z.ZodType<TOutput>;
+    }): Promise<TOutput>;
+    readText(input: {
+        chatId: string;
+        maxCharacters?: number;
+        path: string;
+    }): Promise<string>;
+    writeJson(input: {
+        data: unknown;
+        path: string;
+    }): Promise<{
+        path: string;
+        sizeBytes: number;
+    }>;
+    writeText(input: {
+        content: string;
+        path: string;
+    }): Promise<{
+        path: string;
+        sizeBytes: number;
+    }>;
+};
+export type ExtensionBackendConnectorExecuteInput = {
+    connector: string;
+    params: unknown;
+    requestId?: string;
+    resourceSnapshot?: Record<string, unknown>;
+};
+export type ExtensionBackendConnectorResult = {
+    connector: string;
+    data?: unknown;
+    ok: boolean;
+} & Record<string, unknown>;
+export type ExtensionBackendConnectorsClient = {
+    execute(input: ExtensionBackendConnectorExecuteInput): Promise<ExtensionBackendConnectorResult>;
+};
+export type ExtensionBackendResourcesClient = {
+    documents: {
+        update(input: {
+            content: ExtensionDocumentContentInput;
+            resourceKey: string;
+        }): Promise<unknown>;
+    };
+    records: {
+        create<TData extends Record<string, unknown>>(input: {
+            data: TData;
+            resourceKey: string;
+            scopeResourceId?: string | null;
+        }): Promise<ExtensionTableRecord<TData>>;
+        update<TData extends Record<string, unknown>>(input: {
+            data: Partial<TData>;
+            recordId: string;
+            resourceKey: string;
+            scopeResourceId?: string | null;
+        }): Promise<ExtensionTableRecord<TData>>;
+    };
+};
+export type ExtensionBackendAgentRunInput = {
+    chatId?: string;
+    message: string;
+    metadata?: Record<string, unknown>;
+    onSettledAction?: {
+        action: string;
+        input: Record<string, unknown>;
+    };
+    visibility?: "hidden" | "visible";
+};
+export type ExtensionBackendAgentHandle = {
+    run(input: ExtensionBackendAgentRunInput): Promise<{
+        agentRunId: string;
+        chatId: string;
+    }>;
+};
+export type ExtensionBackendSdk = {
+    agents: Record<string, ExtensionBackendAgentHandle>;
+    artifacts: ExtensionBackendArtifactsClient;
+    connectors: ExtensionBackendConnectorsClient;
+    resources: ExtensionBackendResourcesClient;
+    state: {
+        records: ExtensionBackendStateRecordsClient;
+    };
+};
+export type ExtensionBackendActionContext = {
+    extension: {
+        appResourceId: string;
+        resources: ExtensionResolvedResource[];
+    };
+    organizationId: string;
+    principalUserId: string;
+    workspaceId: string;
+};
+export type ExtensionBackendActionHandlerInput<TInput, TSdk> = {
+    context: ExtensionBackendActionContext;
+    input: TInput;
+    sdk: TSdk;
+};
+export type ExtensionBackendHandlers<TActions extends ExtensionActionsInput, TSdk> = {
+    [TAction in keyof TActions & string]: (input: ExtensionBackendActionHandlerInput<ExtensionActionInput<TActions, TAction>, TSdk>) => ExtensionActionOutput<TActions, TAction> | Promise<ExtensionActionOutput<TActions, TAction>>;
+};
+export type ExtensionBackendActionDefinition<TInput = unknown, TOutput = unknown, TSdk = ExtensionBackendSdk> = {
+    handler: (input: ExtensionBackendActionHandlerInput<TInput, TSdk>) => Promise<TOutput>;
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+};
+export type ExtensionBackendDefinition<TActions extends ExtensionActionsInput, TSdk = ExtensionBackendSdk> = {
+    actions: {
+        [TAction in keyof TActions & string]: ExtensionBackendActionDefinition<ExtensionActionInput<TActions, TAction>, ExtensionActionOutput<TActions, TAction>, TSdk>;
+    };
+};
+export declare function defineBackendActions<const TActions extends ExtensionActionsInput, TSdk = ExtensionBackendSdk>(actions: TActions, handlers: ExtensionBackendHandlers<TActions, TSdk>): ExtensionBackendDefinition<TActions, TSdk>;
+export {};
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

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

package/dist/backend.js

@@ -0,0 +1,16 @@
+export function defineBackendActions(actions, handlers) {
+    const backendActions = {};
+    for (const action of Object.keys(actions)) {
+        const actionContract = actions[action];
+        const handler = handlers[action];
+        backendActions[action] = {
+            handler: async (handlerInput) => actionContract.outputSchema.parse(await handler(handlerInput)),
+            inputSchema: actionContract.inputSchema,
+            outputSchema: actionContract.outputSchema,
+        };
+    }
+    return {
+        actions: backendActions,
+    };
+}
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAyMA,MAAM,UAAU,oBAAoB,CAIlC,OAAiB,EACjB,QAAkD;IAElD,MAAM,cAAc,GAGhB,EAAE,CAAC;IAEP,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEjC,cAAc,CAAC,MAAM,CAAC,GAAG;YACvB,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAC9B,cAAc,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;YAChE,WAAW,EAAE,cAAc,CAAC,WAAW;YACvC,YAAY,EAAE,cAAc,CAAC,YAAY;SAC1C,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,cAAc;KACsB,CAAC;AAClD,CAAC"}

package/dist/context.d.ts

@@ -4,6 +4,50 @@ export type ExtensionSdkListContextResourceChildrenInput = ListContextResourceCh
 export type ExtensionSdkListContextResourceChildrenOutput = ListContextResourceChildrenOutput;
 export type ExtensionContextResourceListChildren = OrpcContractsContextResourceListChildren;
 export type ExtensionContextResourcesClient = OrpcContractsContextResourcesClient;
+export type ExtensionDocumentContentInput = {
+    format: "markdown";
+    markdown: string;
+} | {
+    format: "plainText";
+    text: string;
+} | {
+    doc: unknown;
+    format: "tiptapJson";
+};
+export type ExtensionDocumentOutputFormat = "markdown" | "plainText" | "tiptapJson";
+type AwaitedMethodReturn<TMethod> = TMethod extends (...args: never[]) => infer TReturn ? Awaited<TReturn> : never;
+type ExtensionContextDocument = AwaitedMethodReturn<OrpcContractsContextClient["documents"]["get"]>;
+export type ExtensionDocumentContentForFormat<TFormat extends ExtensionDocumentOutputFormat | undefined> = TFormat extends "markdown" ? Extract<ExtensionDocumentContentInput, {
+    format: "markdown";
+}> : TFormat extends "plainText" ? Extract<ExtensionDocumentContentInput, {
+    format: "plainText";
+}> : TFormat extends "tiptapJson" ? Extract<ExtensionDocumentContentInput, {
+    format: "tiptapJson";
+}> : unknown;
+export type ExtensionDocument<TBody = unknown> = Omit<ExtensionContextDocument, "body"> & {
+    body: TBody;
+};
+export type ExtensionDocumentForFormat<TFormat extends ExtensionDocumentOutputFormat | undefined = undefined> = ExtensionDocument<ExtensionDocumentContentForFormat<TFormat>>;
+export type ExtensionContextDocumentsClient = Omit<Pick<OrpcContractsContextClient["documents"], "create" | "get" | "getByPath" | "update">, "get" | "getByPath"> & {
+    get<TFormat extends ExtensionDocumentOutputFormat | undefined = undefined>(input: {
+        format?: TFormat;
+        resourceId: string;
+    }): Promise<ExtensionDocumentForFormat<TFormat>>;
+    getByPath<TFormat extends ExtensionDocumentOutputFormat | undefined = undefined>(input: {
+        format?: TFormat;
+        path: string;
+    }): Promise<ExtensionDocumentForFormat<TFormat>>;
+};
 export type ExtensionContextClient = OrpcContractsContextClient;
-export type ExtensionGeaClient = OrpcContractsClient;
+export type ExtensionGeaClient = {
+    agents: Pick<OrpcContractsClient["agents"], "getDefault">;
+    context: {
+        documents: ExtensionContextDocumentsClient;
+        records: Pick<OrpcContractsContextClient["records"], "archive" | "create" | "list" | "update">;
+        resources: Pick<OrpcContractsContextResourcesClient, "listChildren">;
+        tables: Pick<OrpcContractsContextClient["tables"], "create" | "getByPath">;
+        wikis: Pick<OrpcContractsContextClient["wikis"], "create" | "list">;
+    };
+    tasks: Pick<OrpcContractsClient["tasks"], "create" | "getById" | "listDispatchHistory">;
+};
 //# sourceMappingURL=context.d.ts.map