@zhama/tego-plugin-sdk 0.0.0-stage → 1.36.1

package/dist/server.d.ts

@@ -0,0 +1,1808 @@
+import { z } from 'zod';
+import { PluginUserContext } from './frontend.js';
+
+/** Invitation requests never accept platform roles or tenant overrides. */
+declare const accountInviteSchema: z.ZodEffects<z.ZodObject<{
+    requestId: z.ZodString;
+    organizationName: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}>, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}>;
+/** Register immediately without sending email; existing passwords remain unchanged. */
+declare const accountProvisionSchema: z.ZodEffects<z.ZodObject<{
+    requestId: z.ZodString;
+    organizationName: z.ZodString;
+    userId: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    fullName: z.ZodOptional<z.ZodString>;
+    phone: z.ZodOptional<z.ZodString>;
+} & {
+    password: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    password?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    password?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}>, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    password?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}, {
+    requestId: string;
+    organizationName: string;
+    email?: string | undefined;
+    phone?: string | undefined;
+    password?: string | undefined;
+    username?: string | undefined;
+    userId?: string | undefined;
+    fullName?: string | undefined;
+}>;
+interface AccountProvisionResult {
+    id: string;
+    userId: string;
+}
+declare const accountInvitationSchema: z.ZodObject<{
+    invitationId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    invitationId: string;
+}, {
+    invitationId: string;
+}>;
+interface AccountInvitation {
+    id: string;
+    userId: string;
+    status: 'pending' | 'accepted' | 'expired';
+    deliveryStatus: 'pending' | 'sent' | 'failed';
+    error: string;
+    expiresAt: string;
+}
+/** Reset ordinary platform accounts; tenant and privileged roles remain host-controlled. */
+declare const accountPasswordResetSchema: z.ZodObject<{
+    userId: z.ZodString;
+    newPassword: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    userId: string;
+    newPassword: string;
+}, {
+    userId: string;
+    newPassword: string;
+}>;
+interface PluginAccountsApi {
+    /** Requires accounts.provision; platform administrator accounts are protected. */
+    resetPassword(input: z.input<typeof accountPasswordResetSchema>): Promise<{
+        userId: string;
+    }>;
+    provisionUser(input: z.input<typeof accountProvisionSchema>): Promise<AccountProvisionResult>;
+    inviteUser(input: z.input<typeof accountInviteSchema>): Promise<AccountInvitation>;
+    getInvitation(invitationId: string): Promise<AccountInvitation>;
+    resendInvitation(invitationId: string): Promise<AccountInvitation>;
+}
+
+/** Host API 1.20. Only source text is accepted; the host renders in an isolated browser. */
+declare const pluginDiagramSchema: z.ZodObject<{
+    kind: z.ZodEnum<["mermaid", "html"]>;
+    source: z.ZodString;
+    destinationKey: z.ZodString;
+    width: z.ZodDefault<z.ZodNumber>;
+    height: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    kind: "html" | "mermaid";
+    width: number;
+    height: number;
+    source: string;
+    destinationKey: string;
+}, {
+    kind: "html" | "mermaid";
+    source: string;
+    destinationKey: string;
+    width?: number | undefined;
+    height?: number | undefined;
+}>;
+type PluginDiagramInput = z.input<typeof pluginDiagramSchema>;
+interface PluginDiagramResult {
+    key: string;
+    width: number;
+    height: number;
+    size: number;
+    sha256: string;
+    renderer: string;
+}
+interface PluginDiagramsApi {
+    status(): Promise<{
+        ready: boolean;
+        reason?: string;
+    }>;
+    /** Requires diagrams.render. Canvas dimensions are maxima; unused bottom whitespace is removed. */
+    render(input: PluginDiagramInput): Promise<PluginDiagramResult>;
+}
+
+/** A principal names an identity, never an organization's display label. */
+declare const directoryPrincipalSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"user">;
+    id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "user";
+}, {
+    id: string;
+    kind: "user";
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"unit">;
+    id: z.ZodString;
+    includeDescendants: z.ZodDefault<z.ZodBoolean>;
+    roles: z.ZodDefault<z.ZodArray<z.ZodEnum<["owner", "admin", "member", "viewer"]>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    kind: "unit";
+    roles: ("admin" | "viewer" | "owner" | "member")[];
+    includeDescendants: boolean;
+}, {
+    id: string;
+    kind: "unit";
+    roles?: ("admin" | "viewer" | "owner" | "member")[] | undefined;
+    includeDescendants?: boolean | undefined;
+}>]>;
+type DirectoryPrincipal = z.infer<typeof directoryPrincipalSchema>;
+declare const directoryMatchSchema: z.ZodObject<{
+    userId: z.ZodString;
+    principals: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "user";
+    }, {
+        id: string;
+        kind: "user";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"unit">;
+        id: z.ZodString;
+        includeDescendants: z.ZodDefault<z.ZodBoolean>;
+        roles: z.ZodDefault<z.ZodArray<z.ZodEnum<["owner", "admin", "member", "viewer"]>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "unit";
+        roles: ("admin" | "viewer" | "owner" | "member")[];
+        includeDescendants: boolean;
+    }, {
+        id: string;
+        kind: "unit";
+        roles?: ("admin" | "viewer" | "owner" | "member")[] | undefined;
+        includeDescendants?: boolean | undefined;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    principals: ({
+        id: string;
+        kind: "user";
+    } | {
+        id: string;
+        kind: "unit";
+        roles: ("admin" | "viewer" | "owner" | "member")[];
+        includeDescendants: boolean;
+    })[];
+    userId: string;
+}, {
+    principals: ({
+        id: string;
+        kind: "user";
+    } | {
+        id: string;
+        kind: "unit";
+        roles?: ("admin" | "viewer" | "owner" | "member")[] | undefined;
+        includeDescendants?: boolean | undefined;
+    })[];
+    userId: string;
+}>;
+declare const directoryIdentitySchema: z.ZodObject<{
+    userId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    userId: string;
+}, {
+    userId: string;
+}>;
+declare const directoryValidateSchema: z.ZodObject<{
+    principals: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"user">;
+        id: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "user";
+    }, {
+        id: string;
+        kind: "user";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"unit">;
+        id: z.ZodString;
+        includeDescendants: z.ZodDefault<z.ZodBoolean>;
+        roles: z.ZodDefault<z.ZodArray<z.ZodEnum<["owner", "admin", "member", "viewer"]>, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        id: string;
+        kind: "unit";
+        roles: ("admin" | "viewer" | "owner" | "member")[];
+        includeDescendants: boolean;
+    }, {
+        id: string;
+        kind: "unit";
+        roles?: ("admin" | "viewer" | "owner" | "member")[] | undefined;
+        includeDescendants?: boolean | undefined;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    principals: ({
+        id: string;
+        kind: "user";
+    } | {
+        id: string;
+        kind: "unit";
+        roles: ("admin" | "viewer" | "owner" | "member")[];
+        includeDescendants: boolean;
+    })[];
+}, {
+    principals: ({
+        id: string;
+        kind: "user";
+    } | {
+        id: string;
+        kind: "unit";
+        roles?: ("admin" | "viewer" | "owner" | "member")[] | undefined;
+        includeDescendants?: boolean | undefined;
+    })[];
+}>;
+declare const directoryListSchema: z.ZodObject<{
+    kind: z.ZodEnum<["users", "units"]>;
+    search: z.ZodOptional<z.ZodString>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    kind: "users" | "units";
+    limit: number;
+    offset: number;
+    search?: string | undefined;
+    ids?: string[] | undefined;
+}, {
+    kind: "users" | "units";
+    search?: string | undefined;
+    limit?: number | undefined;
+    ids?: string[] | undefined;
+    offset?: number | undefined;
+}>;
+interface DirectoryEntry {
+    id: string;
+    displayName: string;
+    fullName?: string | null;
+    username?: string;
+    email?: string;
+    active: boolean;
+    parentId?: string | null;
+    unitType?: 'team' | 'department' | 'subcompany';
+}
+interface DirectoryMatch {
+    active: boolean;
+    /** Indexes into the request, preserving groups without flattening rules. */
+    matched: number[];
+    checkedAt: string;
+}
+interface DirectoryIdentity {
+    active: boolean;
+    roleNames: string[];
+    memberships: {
+        unitId: string;
+        ancestors: string[];
+        role: 'owner' | 'admin' | 'member' | 'viewer';
+    }[];
+    checkedAt: string;
+}
+interface PluginDirectoryApi {
+    identity(userId: string): Promise<DirectoryIdentity>;
+    validate(principals: DirectoryPrincipal[]): Promise<{
+        invalid: number[];
+    }>;
+    list(input: z.input<typeof directoryListSchema>): Promise<{
+        items: DirectoryEntry[];
+        hasMore: boolean;
+    }>;
+    /** Always reads live tenant membership; this is not a user impersonation API. */
+    match(input: z.input<typeof directoryMatchSchema>): Promise<DirectoryMatch>;
+}
+
+/** An excerpt of existing platform knowledge, not a second knowledge store. */
+declare const pluginKnowledgeReferenceSchema: z.ZodObject<{
+    knowledgeBaseId: z.ZodString;
+    documentId: z.ZodString;
+    paragraphId: z.ZodString;
+    /** Omit to preserve the authoritative paragraph; supplied excerpts must match exactly. */
+    quote: z.ZodOptional<z.ZodString>;
+    /** Optional optimistic check when editing a previously verified source snapshot. */
+    expectedContentSha256: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    documentId: string;
+    knowledgeBaseId: string;
+    paragraphId: string;
+    quote?: string | undefined;
+    expectedContentSha256?: string | undefined;
+}, {
+    documentId: string;
+    knowledgeBaseId: string;
+    paragraphId: string;
+    quote?: string | undefined;
+    expectedContentSha256?: string | undefined;
+}>;
+declare const pluginKnowledgeVerifySchema: z.ZodObject<{
+    userId: z.ZodString;
+    avatarId: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        knowledgeBaseId: z.ZodString;
+        documentId: z.ZodString;
+        paragraphId: z.ZodString;
+        /** Omit to preserve the authoritative paragraph; supplied excerpts must match exactly. */
+        quote: z.ZodOptional<z.ZodString>;
+        /** Optional optimistic check when editing a previously verified source snapshot. */
+        expectedContentSha256: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        documentId: string;
+        knowledgeBaseId: string;
+        paragraphId: string;
+        quote?: string | undefined;
+        expectedContentSha256?: string | undefined;
+    }, {
+        documentId: string;
+        knowledgeBaseId: string;
+        paragraphId: string;
+        quote?: string | undefined;
+        expectedContentSha256?: string | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    avatarId: string;
+    userId: string;
+    references: {
+        documentId: string;
+        knowledgeBaseId: string;
+        paragraphId: string;
+        quote?: string | undefined;
+        expectedContentSha256?: string | undefined;
+    }[];
+}, {
+    avatarId: string;
+    userId: string;
+    references: {
+        documentId: string;
+        knowledgeBaseId: string;
+        paragraphId: string;
+        quote?: string | undefined;
+        expectedContentSha256?: string | undefined;
+    }[];
+}>;
+type PluginKnowledgeReference = z.infer<typeof pluginKnowledgeReferenceSchema>;
+interface VerifiedPluginKnowledgeReference extends PluginKnowledgeReference {
+    quote: string;
+    documentName: string;
+    title: string;
+    /** SHA-256 of the hydrated content snapshot; not a whole-document version. */
+    contentSha256: string;
+    verifiedAt: string;
+}
+declare const PLUGIN_COLLECTION_IMPORT_MAX = 50;
+declare const collectionMetadataSchema: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null>>;
+declare const pluginCollectionEnsureSchema: z.ZodObject<{
+    key: z.ZodString;
+    name: z.ZodString;
+    accessMode: z.ZodOptional<z.ZodEnum<["private", "managed"]>>;
+    /** @deprecated Accepted for older clients; reads use ordinary knowledge ACL. */
+    policyScope: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    name: string;
+    accessMode?: "managed" | "private" | undefined;
+    policyScope?: string | undefined;
+}, {
+    key: string;
+    name: string;
+    accessMode?: "managed" | "private" | undefined;
+    policyScope?: string | undefined;
+}>;
+declare const pluginCollectionPermissionsSchema: z.ZodObject<{
+    key: z.ZodString;
+    syncRevision: z.ZodOptional<z.ZodString>;
+    grants: z.ZodArray<z.ZodObject<{
+        subjectType: z.ZodEnum<["user", "team", "role", "tenant"]>;
+        subjectId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+    }, {
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    grants: {
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+    }[];
+    syncRevision?: string | undefined;
+}, {
+    key: string;
+    grants: {
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+    }[];
+    syncRevision?: string | undefined;
+}>;
+/** Move existing documents without re-embedding; retry with the same migrationId. */
+declare const pluginCollectionMoveSchema: z.ZodEffects<z.ZodObject<{
+    migrationId: z.ZodString;
+    sourceKey: z.ZodString;
+    targetKey: z.ZodString;
+    syncRevision: z.ZodString;
+    externalIds: z.ZodEffects<z.ZodArray<z.ZodString, "many">, string[], string[]>;
+}, "strict", z.ZodTypeAny, {
+    syncRevision: string;
+    migrationId: string;
+    sourceKey: string;
+    targetKey: string;
+    externalIds: string[];
+}, {
+    syncRevision: string;
+    migrationId: string;
+    sourceKey: string;
+    targetKey: string;
+    externalIds: string[];
+}>, {
+    syncRevision: string;
+    migrationId: string;
+    sourceKey: string;
+    targetKey: string;
+    externalIds: string[];
+}, {
+    syncRevision: string;
+    migrationId: string;
+    sourceKey: string;
+    targetKey: string;
+    externalIds: string[];
+}>;
+/** Suspend reads while a plugin synchronizes ordinary ACLs. */
+declare const pluginCollectionAccessSchema: z.ZodEffects<z.ZodObject<{
+    key: z.ZodOptional<z.ZodString>;
+    /** Omit to inspect the identity snapshot without changing read access. */
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    syncRevision: z.ZodOptional<z.ZodString>;
+    /** Identity snapshot returned by access({enabled:false}); required to resume. */
+    identityRevision: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    key?: string | undefined;
+    enabled?: boolean | undefined;
+    syncRevision?: string | undefined;
+    identityRevision?: string | undefined;
+}, {
+    key?: string | undefined;
+    enabled?: boolean | undefined;
+    syncRevision?: string | undefined;
+    identityRevision?: string | undefined;
+}>, {
+    key?: string | undefined;
+    enabled?: boolean | undefined;
+    syncRevision?: string | undefined;
+    identityRevision?: string | undefined;
+}, {
+    key?: string | undefined;
+    enabled?: boolean | undefined;
+    syncRevision?: string | undefined;
+    identityRevision?: string | undefined;
+}>;
+declare const pluginCollectionImportSchema: z.ZodObject<{
+    key: z.ZodString;
+    syncRevision: z.ZodOptional<z.ZodString>;
+    documents: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        externalId: z.ZodString;
+        title: z.ZodString;
+        text: z.ZodString;
+        metadata: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null>>>;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }, {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }>, "many">, {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[], {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    documents: {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[];
+    syncRevision?: string | undefined;
+}, {
+    key: string;
+    documents: {
+        title: string;
+        text: string;
+        externalId: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[];
+    syncRevision?: string | undefined;
+}>;
+declare const pluginCollectionImportFilesSchema: z.ZodObject<{
+    key: z.ZodString;
+    syncRevision: z.ZodOptional<z.ZodString>;
+    documents: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        externalId: z.ZodString;
+        title: z.ZodString;
+        storageKey: z.ZodString;
+        fileName: z.ZodString;
+        contentSha256: z.ZodString;
+        metadata: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>, Record<string, string | number | boolean | null>, Record<string, string | number | boolean | null>>>;
+    }, "strict", z.ZodTypeAny, {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }, {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }>, "many">, {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[], {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    documents: {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[];
+    syncRevision?: string | undefined;
+}, {
+    key: string;
+    documents: {
+        title: string;
+        externalId: string;
+        storageKey: string;
+        fileName: string;
+        contentSha256: string;
+        metadata?: Record<string, string | number | boolean | null> | undefined;
+    }[];
+    syncRevision?: string | undefined;
+}>;
+declare const pluginCollectionStatusSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+declare const pluginCollectionDeleteSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+declare const pluginCollectionDocumentsStatusSchema: z.ZodObject<{
+    key: z.ZodString;
+    externalIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    offset?: number | undefined;
+    externalIds?: string[] | undefined;
+}, {
+    key: string;
+    offset?: number | undefined;
+    externalIds?: string[] | undefined;
+}>;
+declare const PLUGIN_COLLECTION_CONTENT_PAGE_MAX = 100;
+declare const pluginCollectionDocumentContentSchema: z.ZodObject<{
+    key: z.ZodString;
+    externalId: z.ZodString;
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    page: number;
+    externalId: string;
+    pageSize: number;
+}, {
+    key: string;
+    externalId: string;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+}>;
+declare const pluginCollectionSearchSchema: z.ZodObject<{
+    key: z.ZodString;
+    query: z.ZodString;
+    topK: z.ZodDefault<z.ZodNumber>;
+    /** Equality per key; an array matches any of its values. */
+    filter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>, "many">]>>>;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    query: string;
+    topK: number;
+    filter?: Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | undefined;
+}, {
+    key: string;
+    query: string;
+    filter?: Record<string, string | number | boolean | (string | number | boolean | null)[] | null> | undefined;
+    topK?: number | undefined;
+}>;
+declare const pluginCollectionRemoveSchema: z.ZodObject<{
+    key: z.ZodString;
+    externalIds: z.ZodArray<z.ZodString, "many">;
+}, "strict", z.ZodTypeAny, {
+    key: string;
+    externalIds: string[];
+}, {
+    key: string;
+    externalIds: string[];
+}>;
+type PluginCollectionMetadata = z.infer<typeof collectionMetadataSchema>;
+type PluginCollectionStatus = 'empty' | 'indexing' | 'partial' | 'ready';
+/** One paragraph of a document as the knowledge service split it. */
+interface PluginCollectionParagraph {
+    title: string;
+    content: string;
+    /** 1-based reading order within the document. */
+    position: number;
+    /** Source pages, for PDFs; null when the format has no pages. */
+    pageStart: number | null;
+    pageEnd: number | null;
+}
+interface PluginCollectionsApi {
+    ensure(input: z.input<typeof pluginCollectionEnsureSchema>): Promise<{
+        collectionId: string;
+        status: 'ready';
+    }>;
+    /** Project a managed plugin's reader principals onto the host KB ACL. */
+    permissions(input: z.input<typeof pluginCollectionPermissionsSchema>): Promise<{
+        aclVersion: number;
+    }>;
+    move(input: z.input<typeof pluginCollectionMoveSchema>): Promise<{
+        moved: number;
+        documentIds: string[];
+    }>;
+    access(input: z.input<typeof pluginCollectionAccessSchema>): Promise<{
+        enabled: boolean;
+        identityRevision: string;
+        syncRevision: string;
+        validUntil: string | null;
+    }>;
+    import(input: z.input<typeof pluginCollectionImportSchema>): Promise<{
+        accepted: number;
+        taskId: string;
+    }>;
+    importFiles(input: z.input<typeof pluginCollectionImportFilesSchema>): Promise<{
+        accepted: number;
+        taskId: string;
+    }>;
+    status(input: z.input<typeof pluginCollectionStatusSchema>): Promise<{
+        status: PluginCollectionStatus;
+        documents: number;
+        pending: number;
+        failed: number;
+        updatedAt: string;
+    }>;
+    /** Permanently retire a collection key and its knowledge base. */
+    delete(input: z.input<typeof pluginCollectionDeleteSchema>): Promise<{
+        deleted: boolean;
+    }>;
+    documentsStatus(input: z.input<typeof pluginCollectionDocumentsStatusSchema>): Promise<{
+        hasMore?: boolean;
+        documents: Array<{
+            externalId: string;
+            state: 'processing' | 'ready' | 'failed' | 'cancelled';
+            contentSha256: string;
+            metadata: PluginCollectionMetadata;
+        }>;
+    }>;
+    /**
+     * The full parsed text of one ready document, in reading order, a page of
+     * paragraphs at a time. A document still indexing or failed is a 409.
+     */
+    documentContent(input: z.input<typeof pluginCollectionDocumentContentSchema>): Promise<{
+        paragraphs: PluginCollectionParagraph[];
+        total: number;
+        page: number;
+        pageSize: number;
+    }>;
+    search(input: z.input<typeof pluginCollectionSearchSchema>): Promise<{
+        hits: Array<{
+            externalId: string;
+            documentId: string;
+            paragraphId: string;
+            score: number;
+            snippet: string;
+            metadata: PluginCollectionMetadata;
+        }>;
+    }>;
+    remove(input: z.input<typeof pluginCollectionRemoveSchema>): Promise<{
+        removed: number;
+    }>;
+}
+interface PluginKnowledgeApi {
+    /** Requires knowledge.read and this person's live work delegation to the employee. */
+    verify(input: z.infer<typeof pluginKnowledgeVerifySchema>): Promise<{
+        references: VerifiedPluginKnowledgeReference[];
+    }>;
+    /** Knowledge collections owned by this install. Requires knowledge.collections. */
+    collections?: PluginCollectionsApi;
+}
+
+declare const pluginKnowledgeListInputSchema: z.ZodObject<{
+    actionProof: z.ZodString;
+    search: z.ZodOptional<z.ZodString>;
+    sourceDepartments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        externalId: z.ZodString;
+        path: z.ZodArray<z.ZodString, "many">;
+        sourceVersion: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string[];
+        externalId: string;
+        sourceVersion: string;
+    }, {
+        path: string[];
+        externalId: string;
+        sourceVersion: string;
+    }>, "many">>;
+    departmentExternalIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sourceDocumentIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    actionProof: string;
+    search?: string | undefined;
+    sourceDepartments?: {
+        path: string[];
+        externalId: string;
+        sourceVersion: string;
+    }[] | undefined;
+    departmentExternalIds?: string[] | undefined;
+    sourceDocumentIds?: string[] | undefined;
+}, {
+    actionProof: string;
+    search?: string | undefined;
+    sourceDepartments?: {
+        path: string[];
+        externalId: string;
+        sourceVersion: string;
+    }[] | undefined;
+    departmentExternalIds?: string[] | undefined;
+    sourceDocumentIds?: string[] | undefined;
+}>;
+declare const pluginAdminActionSchema: z.ZodEnum<["knowledge.list", "knowledge.create.preview", "knowledge.create", "knowledge.document.prepare", "knowledge.document.preview", "knowledge.document.import", "knowledge.task.read"]>;
+type PluginAdminAction = z.infer<typeof pluginAdminActionSchema>;
+declare const pluginApprovalDigestSchema: z.ZodString;
+declare const pluginAdminProofSchema: z.ZodObject<{
+    action: z.ZodEnum<["knowledge.list", "knowledge.create.preview", "knowledge.create", "knowledge.document.prepare", "knowledge.document.preview", "knowledge.document.import", "knowledge.task.read"]>;
+    digest: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    action: "knowledge.list" | "knowledge.create.preview" | "knowledge.create" | "knowledge.document.prepare" | "knowledge.document.preview" | "knowledge.document.import" | "knowledge.task.read";
+    digest: string;
+}, {
+    action: "knowledge.list" | "knowledge.create.preview" | "knowledge.create" | "knowledge.document.prepare" | "knowledge.document.preview" | "knowledge.document.import" | "knowledge.task.read";
+    digest: string;
+}>;
+declare const pluginKnowledgeBaseInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    scope: z.ZodObject<{
+        type: z.ZodLiteral<"team">;
+        teamId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        type: "team";
+        teamId: string;
+    }, {
+        type: "team";
+        teamId: string;
+    }>;
+    grants: z.ZodArray<z.ZodObject<{
+        subjectType: z.ZodEnum<["user", "role", "team", "tenant"]>;
+        subjectId: z.ZodString;
+        permission: z.ZodEnum<["view", "use", "operate", "manage"]>;
+        expiresAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, "strict", z.ZodTypeAny, {
+        permission: "view" | "manage" | "use" | "operate";
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+        expiresAt?: string | null | undefined;
+    }, {
+        permission: "view" | "manage" | "use" | "operate";
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+        expiresAt?: string | null | undefined;
+    }>, "many">;
+    idempotencyKey: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    scope: {
+        type: "team";
+        teamId: string;
+    };
+    name: string;
+    grants: {
+        permission: "view" | "manage" | "use" | "operate";
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+        expiresAt?: string | null | undefined;
+    }[];
+    idempotencyKey: string;
+    description?: string | undefined;
+}, {
+    scope: {
+        type: "team";
+        teamId: string;
+    };
+    name: string;
+    grants: {
+        permission: "view" | "manage" | "use" | "operate";
+        subjectType: "tenant" | "user" | "team" | "role";
+        subjectId: string;
+        expiresAt?: string | null | undefined;
+    }[];
+    idempotencyKey: string;
+    description?: string | undefined;
+}>;
+type PluginKnowledgeBaseInput = z.infer<typeof pluginKnowledgeBaseInputSchema>;
+declare const pluginDocumentContentInputSchema: z.ZodObject<{
+    knowledgeBaseId: z.ZodString;
+    objectKey: z.ZodString;
+    fileName: z.ZodEffects<z.ZodString, string, string>;
+    sha256: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    knowledgeBaseId: string;
+    fileName: string;
+    objectKey: string;
+    sha256: string;
+}, {
+    knowledgeBaseId: string;
+    fileName: string;
+    objectKey: string;
+    sha256: string;
+}>;
+type PluginDocumentContentInput = z.infer<typeof pluginDocumentContentInputSchema>;
+declare const pluginDocumentBatchItemSchema: z.ZodObject<{
+    knowledgeBaseId: z.ZodString;
+    objectKey: z.ZodString;
+    fileName: z.ZodEffects<z.ZodString, string, string>;
+    sha256: z.ZodString;
+} & {
+    sourceDocumentId: z.ZodString;
+    sourceVersion: z.ZodString;
+    sourceDigest: z.ZodString;
+    attachmentDigest: z.ZodString;
+    contentType: z.ZodLiteral<"text/markdown">;
+    idempotencyKey: z.ZodString;
+    departmentExternalId: z.ZodString;
+    departmentPath: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    departmentSourceVersion: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodString;
+    bindingRevision: z.ZodNumber;
+    departmentMappingDigest: z.ZodOptional<z.ZodString>;
+    baseAclVersion: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    knowledgeBaseId: string;
+    fileName: string;
+    sourceVersion: string;
+    teamId: string;
+    idempotencyKey: string;
+    objectKey: string;
+    sha256: string;
+    sourceDocumentId: string;
+    sourceDigest: string;
+    attachmentDigest: string;
+    contentType: "text/markdown";
+    departmentExternalId: string;
+    bindingRevision: number;
+    baseAclVersion: number;
+    departmentPath?: string[] | undefined;
+    departmentSourceVersion?: string | undefined;
+    departmentMappingDigest?: string | undefined;
+}, {
+    knowledgeBaseId: string;
+    fileName: string;
+    sourceVersion: string;
+    teamId: string;
+    idempotencyKey: string;
+    objectKey: string;
+    sha256: string;
+    sourceDocumentId: string;
+    sourceDigest: string;
+    attachmentDigest: string;
+    contentType: "text/markdown";
+    departmentExternalId: string;
+    bindingRevision: number;
+    baseAclVersion: number;
+    departmentPath?: string[] | undefined;
+    departmentSourceVersion?: string | undefined;
+    departmentMappingDigest?: string | undefined;
+}>;
+type PluginDocumentBatchItem = z.infer<typeof pluginDocumentBatchItemSchema>;
+declare const pluginDocumentBatchInputSchema: z.ZodEffects<z.ZodObject<{
+    ruleVersion: z.ZodNumber;
+    items: z.ZodEffects<z.ZodArray<z.ZodObject<{
+        knowledgeBaseId: z.ZodString;
+        objectKey: z.ZodString;
+        fileName: z.ZodEffects<z.ZodString, string, string>;
+        sha256: z.ZodString;
+    } & {
+        sourceDocumentId: z.ZodString;
+        sourceVersion: z.ZodString;
+        sourceDigest: z.ZodString;
+        attachmentDigest: z.ZodString;
+        contentType: z.ZodLiteral<"text/markdown">;
+        idempotencyKey: z.ZodString;
+        departmentExternalId: z.ZodString;
+        departmentPath: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+        departmentSourceVersion: z.ZodOptional<z.ZodString>;
+        teamId: z.ZodString;
+        bindingRevision: z.ZodNumber;
+        departmentMappingDigest: z.ZodOptional<z.ZodString>;
+        baseAclVersion: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }, {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }>, "many">, {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[], {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[]>;
+}, "strict", z.ZodTypeAny, {
+    items: {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[];
+    ruleVersion: number;
+}, {
+    items: {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[];
+    ruleVersion: number;
+}>, {
+    items: {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[];
+    ruleVersion: number;
+}, {
+    items: {
+        knowledgeBaseId: string;
+        fileName: string;
+        sourceVersion: string;
+        teamId: string;
+        idempotencyKey: string;
+        objectKey: string;
+        sha256: string;
+        sourceDocumentId: string;
+        sourceDigest: string;
+        attachmentDigest: string;
+        contentType: "text/markdown";
+        departmentExternalId: string;
+        bindingRevision: number;
+        baseAclVersion: number;
+        departmentPath?: string[] | undefined;
+        departmentSourceVersion?: string | undefined;
+        departmentMappingDigest?: string | undefined;
+    }[];
+    ruleVersion: number;
+}>;
+type PluginDocumentBatchInput = z.infer<typeof pluginDocumentBatchInputSchema>;
+interface PluginApprovedRequest<T> {
+    actionProof: string;
+    approvedDigest: string;
+    input: T;
+}
+declare const pluginApprovedSchema: <T extends z.ZodType>(input: T) => z.ZodObject<{
+    actionProof: z.ZodString;
+    approvedDigest: z.ZodString;
+    input: T;
+}, "strict", z.ZodTypeAny, z.objectUtil.addQuestionMarks<z.baseObjectOutputType<{
+    actionProof: z.ZodString;
+    approvedDigest: z.ZodString;
+    input: T;
+}>, any> extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never, z.baseObjectInputType<{
+    actionProof: z.ZodString;
+    approvedDigest: z.ZodString;
+    input: T;
+}> extends infer T_2 ? { [k_1 in keyof T_2]: T_2[k_1]; } : never>;
+interface PluginDocumentPreviewItem {
+    sourceDocumentId: string;
+    action: 'create' | 'update' | 'move';
+    knowledgeBaseId: string;
+    previousKnowledgeBaseId?: string;
+    documentId?: string;
+    sha256: string;
+    scope: {
+        type: 'team';
+        teamId: string;
+    };
+    aclVersion: number;
+    inheritedGrants: PluginKnowledgeBaseInput['grants'];
+    issues: string[];
+}
+interface PluginKnowledgeAdminApi {
+    listManageableBases(input: {
+        actionProof: string;
+        search?: string;
+        departmentExternalIds?: string[];
+        sourceDepartments?: {
+            externalId: string;
+            path: string[];
+            sourceVersion: string;
+        }[];
+        sourceDocumentIds?: string[];
+    }): Promise<{
+        departmentMatching?: 'path-v1';
+        localDepartmentCount?: number;
+        departments?: {
+            externalId: string;
+            teamId: string | null;
+            mappingDigest: string | null;
+            issue: string | null;
+        }[];
+        syncLocations?: {
+            sourceDocumentId: string;
+            knowledgeBaseId: string;
+            name: string;
+            documentId: string;
+        }[];
+        syncStates?: {
+            sourceDocumentId: string;
+            knowledgeBaseId: string;
+            name?: string;
+            status: string;
+            error: string | null;
+        }[];
+        items: {
+            id: string;
+            name: string;
+            status: string;
+            scope: {
+                type: 'team';
+                teamId: string;
+            };
+            aclVersion: number;
+            grants: PluginKnowledgeBaseInput['grants'];
+        }[];
+    }>;
+    previewCreateBase(input: PluginApprovedRequest<PluginKnowledgeBaseInput>): Promise<{
+        digest: string;
+        valid: boolean;
+        issues: string[];
+    }>;
+    createApprovedBase(input: PluginApprovedRequest<PluginKnowledgeBaseInput>): Promise<{
+        id: string;
+        status: string;
+    }>;
+    prepareDocumentContent(input: PluginApprovedRequest<PluginDocumentContentInput>): Promise<{
+        text: string;
+        sha256: string;
+    }>;
+    previewDocumentBatch(input: PluginApprovedRequest<PluginDocumentBatchInput>): Promise<{
+        digest: string;
+        inputDigest: string;
+        valid: boolean;
+        issues: string[];
+        count: number;
+        items: PluginDocumentPreviewItem[];
+        summary: {
+            create: number;
+            update: number;
+            move: number;
+        };
+    }>;
+    stageApprovedDocumentBatch(input: PluginApprovedRequest<PluginDocumentBatchInput> & {
+        taskId?: string;
+    }): Promise<{
+        taskId: string;
+        status: 'queued';
+    }>;
+    getTask(input: {
+        actionProof?: string;
+        taskId: string;
+    }): Promise<Record<string, unknown>>;
+}
+
+/**
+ * What a plugin's backend part exports, and the capabilities the host lends it.
+ *
+ * The backend runs as its own process under a sandbox, never inside the API
+ * process — that process holds every tenant's database credentials. Everything
+ * it can reach arrives through {@link PluginHostApi}, so the capability list is
+ * literally the blast radius.
+ */
+
+/**
+ * How a backend learns who is calling.
+ *
+ * Declared here because both ends read it: the platform's gateway sets these
+ * after it has authenticated the caller, and `serveBackend` parses them back
+ * into a {@link PluginUserContext}. A copy on each side would be a contract
+ * that can drift silently — the backend would simply see no user.
+ *
+ * There is deliberately no token among them. A plugin runs third-party code,
+ * and the caller's token authorizes the whole platform API, so handing it over
+ * would make every backend a place from which the user's account can be
+ * driven. This is also why a plugin is told never to parse a token: there is
+ * none to parse.
+ */
+declare const PLUGIN_CONTEXT_HEADERS: {
+    readonly userId: "x-tego-plugin-user-id";
+    readonly tenantId: "x-tego-plugin-tenant-id";
+    /** JSON array, so a role name containing a separator cannot be mis-split. */
+    readonly roles: "x-tego-plugin-roles";
+    /**
+     * Present only when a claw container is the caller. Without it a backend
+     * cannot tell which of the tenant's avatars is asking — every container
+     * authenticates on its own gateway token, and they all resolve to the
+     * avatar owner's user id.
+     */
+    readonly avatarId: "x-tego-plugin-avatar-id";
+    readonly delegation: "x-tego-plugin-delegation";
+    /**
+     * Unix milliseconds at which the gateway signed the four above.
+     *
+     * Signed along with them, so it cannot be moved forward to extend the life
+     * of a captured header set.
+     */
+    readonly issuedAt: "x-tego-plugin-issued-at";
+    /**
+     * HMAC over the identity, keyed per install — see `gateway-signature`.
+     *
+     * Without it the identity is whatever the socket claims, which is only as
+     * strong as the network the backend sits on.
+     */
+    readonly signature: "x-tego-plugin-signature";
+    /** `1` on an anonymous request to a declared public route; see below. */
+    readonly public: "x-tego-plugin-public";
+    readonly installId: "x-tego-plugin-install-id";
+    readonly publicRoute: "x-tego-plugin-public-route";
+    readonly clientIp: "x-tego-plugin-client-ip";
+};
+/**
+ * An anonymous request to a route `parts.backend.publicRoutes` declares.
+ *
+ * Carries no identity and no permission. Whatever token the path holds (a QR
+ * link's, say) is the plugin's to check; the platform only vouches that the
+ * route was declared and the install is enabled.
+ */
+interface PluginPublicContext {
+    tenantId: string;
+    installId: string;
+    avatarId?: string;
+    /** The matched declaration, e.g. `POST /public/trainings/:token/sign`. */
+    route: string;
+    clientIp: string;
+}
+/**
+ * Parameterized SQL against the plugin's own Postgres schema.
+ *
+ * The connection uses a role granted DML on that schema and nothing else, with
+ * `search_path` pinned to it. No ORM is imposed: a plugin can layer Drizzle or
+ * Kysely on top, and inventing a query-builder RPC here would freeze one
+ * opinion into the contract forever.
+ */
+interface PluginScopedDb {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+    /**
+     * Runs `body` on a single connection, wrapped in `BEGIN` / `COMMIT`.
+     *
+     * `query` above takes a connection from the pool per call, so a `BEGIN` and
+     * its `COMMIT` would land on different connections and neither would mean
+     * anything. Without this, a plugin whose write has to be atomic across
+     * tables has one option left: phrase the whole thing as a single statement
+     * with data-modifying CTEs. That works, and it stops working as soon as the
+     * write is conditional on the row it is about.
+     *
+     * Throwing from `body` rolls back and re-throws. The transaction holds a
+     * connection for as long as `body` runs, so a body that awaits something
+     * slow — an HTTP call, say — is holding one of a small number of them: the
+     * host bounds that from the database side rather than trusting plugins.
+     */
+    transaction<T>(body: (tx: PluginTransaction) => Promise<T>): Promise<T>;
+}
+/**
+ * The one connection a {@link PluginScopedDb.transaction} body writes through.
+ *
+ * Deliberately without a nested `transaction`: Postgres has no nested
+ * transactions, only savepoints, and a method that silently meant something
+ * weaker than its name would be worse than its absence.
+ */
+interface PluginTransaction {
+    query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>;
+}
+/** Object storage confined to the plugin's own key prefix. */
+interface PluginManagedDownloadPolicy {
+    subject: {
+        kind: 'user';
+        userId: string;
+    } | {
+        kind: 'public';
+        grantId: string;
+    };
+    /** Optional domain ID used by CRM-style plugins; generic resources use resourceId. */
+    customerId?: number;
+    resourceType: string;
+    resourceId: string;
+    purpose: 'view' | 'export';
+}
+interface PluginScopedStorage {
+    /** Host API 1.19; namespace-scoped transfers, requiring storage.transfer. */
+    copy?(sourceKey: string, destinationKey: string): Promise<PluginObjectHead>;
+    getStream?(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    putStream?(key: string, body: ReadableStream<Uint8Array>, options: {
+        sizeBytes: number;
+        contentType?: string;
+    }): Promise<void>;
+    /** Up to 25 MB; larger objects go through {@link uploadPath}. */
+    put(key: string, body: Uint8Array, contentType?: string): Promise<void>;
+    /**
+     * The object, or only its first `firstBytes` — enough to check a file
+     * signature without pulling a large upload into this process.
+     */
+    get(key: string, options?: {
+        firstBytes?: number;
+    }): Promise<Uint8Array | null>;
+    /** Size and stored type, without reading the object. */
+    head(key: string): Promise<PluginObjectHead | null>;
+    delete(key: string): Promise<void>;
+    /**
+     * Short-lived download URL, for handing large objects to the browser.
+     *
+     * Absolute only when the platform knows its public address; prefer
+     * {@link signedPath}, which the frontend resolves with `ctx.hostUrl`.
+     */
+    signedUrl(key: string, ttlSeconds?: number): Promise<string>;
+    /** The same download, as a path for the frontend's `ctx.hostUrl`. */
+    signedPath(key: string, ttlSeconds?: number): Promise<string>;
+    /** Rechecked at the fixed internal storage policy endpoint before every download. */
+    managedPath(key: string, policy: PluginManagedDownloadPolicy, ttlSeconds?: number): Promise<string>;
+    /**
+     * A path the browser can PUT one object to, once — the way to store
+     * something larger than `put` accepts. The body streams straight into
+     * storage without passing through this backend; check it afterwards with
+     * {@link head} and {@link get}'s `firstBytes`.
+     */
+    uploadPath(key: string, options?: {
+        maxBytes?: number;
+        ttlSeconds?: number;
+    }): Promise<PluginObjectUpload>;
+}
+interface PluginObjectHead {
+    /** Opaque content version validator, when supported. Changes whenever the object bytes change. */
+    versionTag?: string;
+    size: number;
+    contentType: string | null;
+}
+interface PluginObjectUpload {
+    /** Resolve with the frontend's `ctx.hostUrl`, then PUT with Content-Length. */
+    path: string;
+    /** The ceiling the host granted: the request's, capped by the platform's. */
+    maxBytes: number;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+interface PluginLogger {
+    debug(message: string, fields?: Record<string, unknown>): void;
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * There is deliberately no way to invoke a tool on a claw instance.
+ *
+ * Reaching claw means acting for a user, and this object belongs to the
+ * container rather than to any one request — so it would need a second kind of
+ * credential, minted per request and carried back. Nothing needs it yet: the
+ * traffic runs the other way, with a plugin's claw part polling a queue its
+ * backend writes. Adding it later is a token design, not a method.
+ */
+/**
+ * The operator-supplied settings for this install's backend part.
+ *
+ * A snapshot plus a way to re-take it, rather than a promise per read. The
+ * values arrive over the host API — which is how a secret stays out of the
+ * container's environment, where `docker inspect` and every crash dump would
+ * find it — and the runtime fetches them once before the backend accepts its
+ * first request, so a handler can read them without awaiting anything.
+ *
+ * Only what `parts.backend.config` declares, with declared defaults applied.
+ * The frontend's and claw's settings are stored separately and are not
+ * reachable from here.
+ */
+interface PluginConfigAccess {
+    /** The settings as of the last fetch. Never null once the backend is serving. */
+    current(): Record<string, unknown>;
+    /**
+     * Re-read them, for a plugin that wants a rotated credential without a
+     * restart. There is no push channel: the platform cannot call into a plugin
+     * backend, so noticing a change is the plugin's own business.
+     */
+    refresh(): Promise<Record<string, unknown>>;
+}
+interface PluginHostApi {
+    pluginId: string;
+    /**
+     * Host API 1.22; the tenant this install belongs to.
+     *
+     * An install serves exactly one tenant, but until now only a request's
+     * `ctx` said which — so `start`, which runs before any request, could not
+     * write a tenant-owned row.
+     */
+    tenantId: string;
+    db: PluginScopedDb;
+    storage: PluginScopedStorage;
+    log: PluginLogger;
+    config: PluginConfigAccess;
+    /** Requires the install's directory.read capability. */
+    directory?: PluginDirectoryApi;
+    /** Creates ordinary accounts only; requires accounts.provision. */
+    accounts?: PluginAccountsApi;
+    /** Verifies citations against the existing platform knowledge and its live ACL. */
+    knowledge?: PluginKnowledgeApi;
+    /** Host API 1.23; explicit administrator approval for ordinary team bases. */
+    knowledgeAdmin?: PluginKnowledgeAdminApi;
+    /** Host API 1.20; isolated HTML and Mermaid PNG rendering. */
+    diagrams?: PluginDiagramsApi;
+    sources?: {
+        /** Revalidates source ownership and capture permission on the host. */
+        read(id: string, actor: {
+            userId: string;
+            avatarId: string;
+            metadataOnly?: boolean;
+        }): Promise<{
+            source: unknown;
+        }>;
+    };
+    /**
+     * A person's live work delegations, as the host holds them.
+     *
+     * A plugin that reassigns durable work between employees needs this: the
+     * delegation is what makes an employee able to execute for that person, and
+     * a handover to an employee they never delegated produces work nobody can
+     * pick up. The plugin cannot answer that from its own tables — the grant
+     * lives on the host and can be revoked there at any time.
+     */
+    delegations?: {
+        list(userId: string): Promise<{
+            delegations: {
+                avatarId: string;
+                enabled: boolean;
+                actions: string[];
+            }[];
+        }>;
+    };
+    events: {
+        /**
+         * Publishes into the tenant's event stream.
+         *
+         * The host prefixes the topic with `plugin.<pluginId>.`, so subscribers
+         * see the namespaced name and a plugin cannot emit an event the platform's
+         * own subscribers would mistake for one of theirs.
+         */
+        publish(topic: string, payload: unknown): Promise<void>;
+    };
+    notifications: {
+        /** Durable direct message, deduplicated per install, event key and recipient. */
+        send(input: {
+            recipientId: string;
+            eventKey: string;
+            title: string;
+            body: string;
+            path: string;
+            priority?: 'normal' | 'urgent';
+        }): Promise<{
+            id: string;
+        }>;
+    };
+    /** Host API 1.26; requires proactive.emit. */
+    proactive?: {
+        /**
+         * Starts the user's event-triggered scheduled tasks listening for this
+         * plugin's `eventType`.
+         *
+         * The host fixes the source to `plugin:<pluginId>`. Redelivering the same
+         * `eventId` returns the runs it already queued, so retrying a failed call
+         * is safe. An event nobody listens for answers no runs, not an error.
+         */
+        emit(input: PluginProactiveEvent): Promise<PluginProactiveEmitResult>;
+    };
+    /** Host API 1.29; requires mail.send. */
+    mail?: {
+        /**
+         * Sends one email from `userId`'s own connected Gmail or Outlook.
+         *
+         * The host picks the sender, appends an unsubscribe link and refuses
+         * (without sending) when the person has not connected a mailbox, has not
+         * allowed this plugin, the tenant turned sending off, the daily limit is
+         * reached or the recipient unsubscribed.
+         *
+         * Providers have no idempotency key, so the promise is at most one email
+         * per `idempotencyKey`: repeating a key returns the first outcome without
+         * sending, and `unknown` means the mailbox may or may not have accepted
+         * it. Only a `failed` key is sent again when repeated.
+         */
+        send(input: PluginMailSendInput): Promise<PluginMailSendResult>;
+        /** Whether `userId` can send through this plugin right now, and why not. */
+        status(userId: string): Promise<PluginMailStatus>;
+        /** Recipients who used the unsubscribe link on this plugin's mail, oldest first. */
+        unsubscribes(input?: {
+            after?: string;
+            limit?: number;
+        }): Promise<{
+            items: PluginMailUnsubscribe[];
+            next?: string;
+        }>;
+    };
+    /** Host API 1.34; requires attention.request. */
+    attention?: {
+        /**
+         * Asks a person to answer questions, approve or take over work on behalf
+         * of `principalUserId` (the person the plugin acts for). The request shows
+         * in the recipient's Messages and by push, under the tenant's attention
+         * policy (who may be asked, rate limits). Same `dedupeKey` to the same
+         * person returns the open request instead of a second one.
+         */
+        request(input: PluginAttentionRequest): Promise<PluginAttentionReceipt>;
+        /** The request as it stands now, including the response once answered. */
+        get(itemId: string): Promise<PluginAttentionStatus>;
+        /** Withdraws an open request; the recipient's alert is cleared. */
+        cancel(itemId: string): Promise<PluginAttentionStatus>;
+    };
+}
+interface PluginAttentionQuestion {
+    id: string;
+    header: string;
+    question: string;
+    multiSelect?: boolean;
+    isOther?: boolean;
+    options?: {
+        label: string;
+        description?: string;
+    }[];
+}
+interface PluginAttentionRequest {
+    principalUserId: string;
+    recipientUserId: string;
+    kind: 'question' | 'approval' | 'handoff';
+    title: string;
+    context?: string;
+    /** Required for `question`; not allowed otherwise. */
+    questions?: PluginAttentionQuestion[];
+    urgent?: boolean;
+    deadlineHours?: number;
+    dedupeKey?: string;
+    /** The plugin's own record, echoed back in `get`. */
+    recordRef?: string;
+}
+interface PluginAttentionReceipt {
+    itemId: string;
+    state: string;
+    reused: boolean;
+    deadlineAt: string;
+}
+interface PluginAttentionStatus {
+    itemId: string;
+    state: 'pending' | 'seen' | 'answered' | 'declined' | 'expired' | 'cancelled';
+    recordRef: string | null;
+    response: {
+        kind: 'question';
+        answers: Record<string, string[]>;
+        note?: string;
+    } | {
+        kind: 'approval';
+        decision: 'approve' | 'reject';
+        note?: string;
+    } | {
+        kind: 'handoff';
+        decision: 'accept';
+        note?: string;
+    } | null;
+    declineReason: string | null;
+    resolvedBy: string | null;
+    resolvedAt: string | null;
+}
+interface PluginMailSendInput {
+    userId: string;
+    /** Up to 200 characters, no whitespace. */
+    idempotencyKey: string;
+    to: string;
+    subject: string;
+    /** Plain text; the host appends the unsubscribe line. */
+    text: string;
+    /** Echoed back with unsubscribes and sent as `X-Tego-Correlation`. */
+    correlationId?: string;
+}
+type PluginMailRefusal = 'not_member' | 'not_connected' | 'connection_broken' | 'not_granted' | 'sending_disabled' | 'recipient_unsubscribed' | 'daily_limit' | 'unavailable';
+type PluginMailSendResult = {
+    status: 'sent';
+    /** Gmail only; Graph's sendMail returns no id. */
+    providerMessageId?: string;
+    threadId?: string;
+    sentAt: number;
+    duplicate: boolean;
+} | {
+    status: 'failed';
+    reason: 'provider_rejected' | 'rate_limited' | 'connection_broken';
+    message: string;
+    duplicate: boolean;
+} | {
+    status: 'unknown';
+    duplicate: boolean;
+} | {
+    status: 'refused';
+    reason: PluginMailRefusal;
+};
+interface PluginMailStatus {
+    state: 'ready' | Exclude<PluginMailRefusal, 'recipient_unsubscribed' | 'daily_limit'>;
+    provider?: 'google' | 'microsoft';
+    email?: string;
+    dailyLimit: number;
+    sentToday: number;
+}
+interface PluginMailUnsubscribe {
+    id: string;
+    email: string;
+    correlationId?: string;
+    at: number;
+}
+interface PluginProactiveEvent {
+    /** The person whose tasks may start; tasks of other people never match. */
+    userId: string;
+    /** Matched verbatim against the task's `eventType`; no whitespace, up to 160 characters. */
+    eventType: string;
+    /** Unique per event within this plugin; no whitespace, up to 100 characters. */
+    eventId: string;
+    occurredAtMs?: number;
+    /**
+     * Shown to the employee as untrusted external content. At most 16,000
+     * characters once serialized.
+     */
+    payload?: Record<string, unknown>;
+}
+interface PluginProactiveEmitResult {
+    /** `plugin:<pluginId>`. */
+    source: string;
+    /**
+     * One entry per matched task, plus one per employee the person can no
+     * longer use (`access-denied`, no `jobId`). `already-running`: the task
+     * was busy and this event did not queue a run — the plugin decides whether
+     * to send the same event again later. `authority-inactive`: the
+     * employee's schedule store cannot be queued from the platform.
+     */
+    runs: Array<{
+        jobId?: string;
+        avatarId: string;
+        accepted: boolean;
+        runId?: string;
+        reason?: 'already-running' | 'authority-inactive' | 'access-denied';
+    }>;
+}
+/**
+ * The default export of a backend part's entry module.
+ *
+ * A web-standard `fetch` handler, so a plugin can hand the request straight to
+ * Hono, which is what the platform itself runs.
+ *
+ * `ctx` is already authenticated: the host verified the caller at the gateway
+ * and passes the resolved identity. A plugin must never parse a token itself —
+ * two implementations of the permission model would eventually disagree.
+ */
+interface PluginBackendModule {
+    /** Only receives verified POSTs at /api/internal/storage/authorize. */
+    authorizeStorage?(request: Request, context: {
+        installId: string;
+        tenantId: string;
+        issuedAt: string;
+        bodyHash: string;
+    }, host: PluginHostApi): Promise<Response>;
+    /** Starts install-scoped background maintenance after database/config readiness. No user identity is implied. */
+    start?(host: PluginHostApi): void | Promise<void>;
+    /** Stops background maintenance and awaits in-flight work during graceful shutdown. */
+    stop?(): void | Promise<void>;
+    fetch(request: Request, ctx: PluginUserContext, host: PluginHostApi): Promise<Response>;
+    /**
+     * Handles public-route requests. Never receives a user request, and `fetch`
+     * never receives a public one. Absent means public requests are answered 404.
+     */
+    fetchPublic?(request: Request, ctx: PluginPublicContext, host: PluginHostApi): Promise<Response>;
+}
+/** Identity helper for inference. */
+declare function definePluginBackend(module: PluginBackendModule): PluginBackendModule;
+
+export { type AccountInvitation, type AccountProvisionResult, type DirectoryEntry, type DirectoryIdentity, type DirectoryMatch, type DirectoryPrincipal, PLUGIN_COLLECTION_CONTENT_PAGE_MAX, PLUGIN_COLLECTION_IMPORT_MAX, PLUGIN_CONTEXT_HEADERS, type PluginAccountsApi, type PluginAdminAction, type PluginApprovedRequest, type PluginAttentionQuestion, type PluginAttentionReceipt, type PluginAttentionRequest, type PluginAttentionStatus, type PluginBackendModule, type PluginCollectionMetadata, type PluginCollectionParagraph, type PluginCollectionStatus, type PluginCollectionsApi, type PluginConfigAccess, type PluginDiagramInput, type PluginDiagramResult, type PluginDiagramsApi, type PluginDirectoryApi, type PluginDocumentBatchInput, type PluginDocumentBatchItem, type PluginDocumentContentInput, type PluginDocumentPreviewItem, type PluginHostApi, type PluginKnowledgeAdminApi, type PluginKnowledgeApi, type PluginKnowledgeBaseInput, type PluginKnowledgeReference, type PluginLogger, type PluginMailRefusal, type PluginMailSendInput, type PluginMailSendResult, type PluginMailStatus, type PluginMailUnsubscribe, type PluginManagedDownloadPolicy, type PluginObjectHead, type PluginObjectUpload, type PluginProactiveEmitResult, type PluginProactiveEvent, type PluginPublicContext, type PluginScopedDb, type PluginScopedStorage, type PluginTransaction, PluginUserContext, type VerifiedPluginKnowledgeReference, accountInvitationSchema, accountInviteSchema, accountPasswordResetSchema, accountProvisionSchema, definePluginBackend, directoryIdentitySchema, directoryListSchema, directoryMatchSchema, directoryPrincipalSchema, directoryValidateSchema, pluginAdminActionSchema, pluginAdminProofSchema, pluginApprovalDigestSchema, pluginApprovedSchema, pluginCollectionAccessSchema, pluginCollectionDeleteSchema, pluginCollectionDocumentContentSchema, pluginCollectionDocumentsStatusSchema, pluginCollectionEnsureSchema, pluginCollectionImportFilesSchema, pluginCollectionImportSchema, pluginCollectionMoveSchema, pluginCollectionPermissionsSchema, pluginCollectionRemoveSchema, pluginCollectionSearchSchema, pluginCollectionStatusSchema, pluginDiagramSchema, pluginDocumentBatchInputSchema, pluginDocumentBatchItemSchema, pluginDocumentContentInputSchema, pluginKnowledgeBaseInputSchema, pluginKnowledgeListInputSchema, pluginKnowledgeReferenceSchema, pluginKnowledgeVerifySchema };