@agentforge-io/sdk-console 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,1009 @@
+export type UserRole = 'user' | 'platform_admin';
+export type TenantRole = 'owner' | 'admin' | 'member';
+/** `GET /auth/me` */
+export interface AuthUser {
+    userId: string;
+    email?: string;
+    name?: string;
+    isApiKey?: boolean;
+    tenantId?: string;
+    role?: UserRole;
+    isPlatformAdmin?: boolean;
+    /** False until the user finishes (or skips) onboarding. */
+    onboardingCompleted?: boolean;
+}
+/** Body of `POST /auth/register`. */
+export interface RegisterInput {
+    email: string;
+    password: string;
+    name?: string;
+    /** Cloudflare Turnstile token. Required when the server has a secret set. */
+    captchaToken?: string;
+}
+/** Body of `POST /auth/login`. */
+export interface LoginInput {
+    email: string;
+    password: string;
+    captchaToken?: string;
+}
+/** Response of login / register / refresh. */
+export interface AuthResult {
+    accessToken: string;
+    refreshToken: string;
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+}
+/** `GET /auth/strategies` */
+export interface AuthStrategies {
+    strategies: Array<{
+        name: 'local' | 'google' | 'github';
+        loginUrl?: string;
+    }>;
+}
+export interface TenantBrand {
+    logoUrl?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    bannerUrl?: string;
+}
+export interface TenantTheme {
+    logoUrl?: string;
+    tagline?: string;
+    bio?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    headerBg?: string;
+    surfaceBg?: string;
+    surfaceFg?: string;
+    font?: 'inter' | 'geist' | 'dm-sans' | 'serif';
+    mode?: 'light' | 'dark' | 'auto';
+    bannerUrl?: string;
+}
+export type OgLayout = 'centered' | 'split' | 'minimal' | 'banner-hero';
+export interface Tenant {
+    id: string;
+    name: string;
+    ownerUserId: string;
+    /** Caller's role in this workspace (filled by `/me/tenants`). */
+    myRole?: TenantRole | null;
+    planId: string;
+    isActive: boolean;
+    timezone?: string;
+    /** @deprecated server promotes it to `theme` at read time. */
+    brand?: TenantBrand;
+    theme?: TenantTheme;
+    publicSlug?: string;
+    visibility: 'private' | 'public';
+    ogLayout?: OgLayout;
+    ogThumbnailUrl?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TenantList {
+    items: Tenant[];
+    total: number;
+    limit: number | null;
+    offset: number;
+}
+export interface ListTenantsInput {
+    q?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Body of `POST /admin/tenants`. */
+export interface CreateTenantInput {
+    name: string;
+    planId?: string;
+}
+/** Body of `PATCH /admin/tenants/:tenantId`. */
+export interface UpdateTenantInput {
+    name?: string;
+    /** `null` clears. */
+    timezone?: string | null;
+    publicSlug?: string | null;
+    visibility?: 'private' | 'public';
+    brand?: TenantBrand | null;
+    theme?: {
+        [K in keyof TenantTheme]?: TenantTheme[K] | null;
+    } | null;
+    ogLayout?: OgLayout;
+}
+/** Row of `GET /admin/tenants/:tenantId/members`. The owner has `id: null`. */
+export interface TenantMember {
+    id: string | null;
+    userId: string;
+    email?: string;
+    name?: string;
+    role: TenantRole;
+    createdAt: string;
+    isOwner: boolean;
+}
+export type HumanCapability = 'receives_escalations' | 'approves_actions' | 'specialist';
+export interface TenantInvite {
+    id: string;
+    email: string;
+    role: 'admin' | 'member';
+    invitedByUserId: string;
+    invitedByName?: string;
+    expiresAt: string;
+    createdAt: string;
+    teamId?: string | null;
+    teamCapabilities?: HumanCapability[];
+}
+export interface CreateInviteInput {
+    email: string;
+    role?: 'member' | 'admin';
+    /** Also add the invitee to this team on accept. */
+    teamId?: string;
+    capabilities?: HumanCapability[];
+}
+/** `GET /invite/:token` (public). */
+export type InvitePreview = {
+    valid: false;
+} | {
+    valid: true;
+    email: string;
+    tenantName: string;
+    role: 'admin' | 'member';
+};
+/** Body of `POST /invite/:token/accept` (public). Creates the account and joins. */
+export interface AcceptInviteInput {
+    password: string;
+    name?: string;
+}
+export type ToolPermissionMode = 'allow' | 'approval' | 'blocked';
+export interface ToolPermissionInput {
+    name: string;
+    mode: ToolPermissionMode;
+}
+/** A bare string means `{ name, mode: 'allow' }`. */
+export type ToolListInput = Array<string | ToolPermissionInput>;
+export interface AgentAppearance {
+    primaryColor?: string;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    title?: string;
+    greeting?: string;
+    avatarUrl?: string;
+}
+export type ModelTier = 'haiku' | 'sonnet' | 'opus';
+export interface ModelStrategy {
+    kind: 'fixed' | 'tiered';
+    default: string;
+    tiers?: {
+        haiku?: string;
+        sonnet?: string;
+        opus?: string;
+    };
+    escalate?: Array<'toolUse' | 'longContext' | 'approvalRequired'>;
+    fallback?: Array<'shortInput'>;
+    thresholds?: {
+        longContextTokens?: number;
+        shortInputTokens?: number;
+    };
+}
+export type AgentEscalationRule = {
+    when: 'customer_asks_for_human';
+    keywords?: string[];
+    assign: HumanCapability;
+} | {
+    when: 'agent_uncertain';
+    assign: HumanCapability;
+} | {
+    when: 'tool_requires_approval';
+    tools?: string[];
+    assign: HumanCapability;
+};
+/** Public-profile blocks / theme are edited by the dashboard only; kept open. */
+export type ProfileBlock = {
+    id: string;
+    enabled: boolean;
+    title?: string;
+    [k: string]: unknown;
+};
+export type ProfileTheme = {
+    [k: string]: unknown;
+};
+export interface Agent {
+    id: string;
+    tenantId: string;
+    slug: string;
+    name: string;
+    description?: string;
+    model?: string;
+    modelStrategy?: ModelStrategy;
+    systemPrompt: string;
+    context?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    /** The platform returns `{name, mode}` entries; older rows may hold plain names. */
+    tools?: ToolListInput;
+    skills?: string[];
+    appearance?: AgentAppearance;
+    timezone?: string;
+    isActive: boolean;
+    visibility: 'private' | 'public';
+    publicSlug?: string;
+    profileTemplate: 'minimal' | 'brand' | 'beacons';
+    profileBlocks?: ProfileBlock[];
+    profileTheme?: ProfileTheme;
+    observerEnabled?: boolean;
+    observerCapture?: {
+        clicks?: boolean;
+        inputs?: boolean;
+        navigation?: boolean;
+        scroll?: boolean;
+    };
+    createdByUserId?: string;
+    metadata?: Record<string, unknown>;
+    escalation?: AgentEscalationRule[];
+    ogLayout?: OgLayout;
+    ogThumbnailUrl?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AgentList {
+    items: Agent[];
+    total: number;
+    limit: number | null;
+    offset: number;
+}
+export interface ListAgentsInput {
+    q?: string;
+    status?: 'active' | 'inactive';
+    limit?: number;
+    offset?: number;
+    /** Only agents created by this App. */
+    appId?: string;
+}
+/** Body of `POST /admin/tenants/:tenantId/agents` (and, partial, of PATCH). */
+export interface AgentInput {
+    slug?: string;
+    name: string;
+    systemPrompt?: string;
+    description?: string;
+    model?: string;
+    /** `null` reverts to the single `model`. */
+    modelStrategy?: ModelStrategy | null;
+    context?: string;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    tools?: ToolListInput;
+    skills?: string[];
+    appearance?: AgentAppearance;
+    isActive?: boolean;
+    visibility?: 'private' | 'public';
+    profileTemplate?: 'minimal' | 'brand' | 'beacons';
+    profileBlocks?: ProfileBlock[];
+    profileTheme?: ProfileTheme | null;
+    observerEnabled?: boolean;
+    observerCapture?: {
+        clicks?: boolean;
+        inputs?: boolean;
+        navigation?: boolean;
+        scroll?: boolean;
+    } | null;
+    /** `null` or `[]` wipes the rules. */
+    escalation?: AgentEscalationRule[] | null;
+    ogLayout?: OgLayout;
+    metadata?: Record<string, unknown>;
+}
+/** `GET .../agents/:agentId/parent-team` */
+export type AgentParentTeam = {
+    teamId: string;
+    teamSlug: string;
+} | {
+    teamId: null;
+};
+export interface ChatToken {
+    token: string;
+    tenantId: string;
+    agentId: string;
+    name: string;
+    allowedOrigins?: string[];
+    isActive: boolean;
+    createdByUserId?: string;
+    lastUsedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ChatTokenInput {
+    name: string;
+    allowedOrigins?: string[];
+}
+export interface TeamTheme {
+    logoUrl?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    headerBg?: string;
+    surfaceBg?: string;
+    surfaceFg?: string;
+    font?: 'inter' | 'geist' | 'dm-sans' | 'serif';
+    mode?: 'light' | 'dark' | 'auto';
+    bannerUrl?: string;
+    personaName?: string;
+    tagline?: string;
+    bio?: string;
+    greeting?: string;
+    shortcuts?: string[];
+    bubbleAgentBg?: string;
+    bubbleAgentFg?: string;
+    bubbleUserBg?: string;
+    bubbleUserFg?: string;
+    sendButtonBg?: string;
+    inputBg?: string;
+    inputFg?: string;
+    avatarBg?: string;
+}
+export type OrchestrationMode = 'flat' | 'hierarchical';
+export interface Team {
+    id: string;
+    tenantId: string;
+    name: string;
+    slug: string;
+    publicSlug?: string;
+    visibility: 'private' | 'public';
+    description?: string;
+    systemPrompt?: string;
+    orchestratorAgentId: string;
+    theme?: TeamTheme;
+    orchestrationMode: OrchestrationMode;
+    profileTemplate?: 'minimal' | 'brand' | 'beacons';
+    profileBlocks?: ProfileBlock[];
+    ogLayout?: OgLayout;
+    ogThumbnailUrl?: string;
+    timezone?: string;
+    humanCloseTimeoutMinutes?: number;
+    humanHandbackTimeoutMinutes?: number;
+    createdAt: string;
+    updatedAt: string;
+    /** Session list / get only. Set when this team is the editable source copy of
+     *  a template («… (plantilla)»): hide it from normal team pickers. `null` for
+     *  any other team. Absent on responses that do not compute it. */
+    templateSourceOf?: TemplateSourceOf | null;
+}
+export interface TemplateSourceOf {
+    templateId: string;
+    templateName: string;
+}
+export interface TeamMember {
+    teamId: string;
+    agentId: string;
+    /** Routing priority: lower reads as "try first". */
+    position: number;
+    roleHint?: string;
+    /** Only meaningful when `orchestrationMode === 'hierarchical'`. */
+    parentAgentId?: string;
+    addedAt: string;
+}
+export interface TeamList {
+    items: Team[];
+    total: number;
+}
+export interface TeamWithMembers {
+    team: Team;
+    members: TeamMember[];
+}
+export interface CreateTeamInput {
+    name: string;
+    slug?: string;
+    description?: string;
+    systemPrompt?: string;
+    /** Order = routing priority. */
+    memberAgentIds: string[];
+    /** Keyed by agentId. */
+    roleHints?: Record<string, string>;
+    publicSlug?: string;
+    visibility?: 'private' | 'public';
+    orchestrationMode?: OrchestrationMode;
+}
+export interface UpdateTeamInput {
+    name?: string;
+    description?: string | null;
+    systemPrompt?: string | null;
+    publicSlug?: string | null;
+    visibility?: 'private' | 'public';
+    /** Replaces the full ordered member list. */
+    members?: Array<{
+        agentId: string;
+        roleHint?: string;
+        parentAgentId?: string | null;
+    }>;
+    theme?: TeamTheme | null;
+    orchestrationMode?: OrchestrationMode;
+    profileTemplate?: 'minimal' | 'brand' | 'beacons' | null;
+    profileBlocks?: ProfileBlock[] | null;
+    ogLayout?: OgLayout;
+    /** IANA timezone; `null` clears. */
+    timezone?: string | null;
+    humanCloseTimeoutMinutes?: number | null;
+    humanHandbackTimeoutMinutes?: number | null;
+}
+/** draft | unverified (reachable, never validated) | published | degraded (published, now failing). */
+export type TeamPublicationStatus = 'draft' | 'unverified' | 'published' | 'degraded';
+export interface TeamPublicationIssue {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    message: string;
+    path?: string;
+    params?: Record<string, string | number>;
+}
+export interface TeamPublication {
+    teamId: string;
+    teamName: string;
+    status: TeamPublicationStatus;
+    canPublish: boolean;
+    exposure: {
+        public: boolean;
+        channels: Array<{
+            kind: 'inbox' | 'voice' | 'whatsapp';
+            count: number;
+        }>;
+    };
+    publishedAt: string | null;
+    publishedByUserId: string | null;
+    issues: TeamPublicationIssue[];
+    /** PDK-CONSOLE G2. Set when checked against an App (`publication(id, { publisherAppId })`):
+     *  `issues` then include that App's policy issues and `canPublish` accounts for them. */
+    publisherApp?: {
+        id: string;
+        name: string;
+    };
+}
+export type TeamPublicationSummary = Pick<TeamPublication, 'teamId' | 'teamName' | 'status' | 'publishedAt' | 'exposure'>;
+export type HumanNotifyVia = {
+    kind: 'slack';
+    slackUserId: string;
+} | {
+    kind: 'whatsapp';
+    phone: string;
+} | {
+    kind: 'email';
+};
+export interface TeamHumanMember {
+    teamId: string;
+    userId: string;
+    capabilities: HumanCapability[];
+    skills?: string[];
+    availability: 'always' | 'business_hours' | 'off';
+    notifyVia?: HumanNotifyVia;
+    position: number;
+    addedAt: string;
+}
+export interface TeamHumanMemberInput {
+    userId: string;
+    capabilities: HumanCapability[];
+    skills?: string[];
+    availability?: 'always' | 'business_hours' | 'off';
+    notifyVia?: HumanNotifyVia;
+    position?: number;
+}
+export interface ToolDescription {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    agents?: string[];
+    connectorId?: string;
+    connectorName?: string;
+    mcpServerName?: string;
+    tenantId?: string;
+}
+/** `GET /tools/grouped` bucket. */
+export interface ToolGroup {
+    id: string;
+    kind: 'connector' | 'mcp' | 'builtin';
+    name: string;
+    iconUrl?: string;
+    description?: string;
+    tools: ToolDescription[];
+}
+export interface ConnectorStatus {
+    connectorId: string;
+    name: string;
+    description: string;
+    category?: string;
+    iconUrl?: string;
+    /** False = the platform has no OAuth credentials for it ("needs admin setup"). */
+    configured: boolean;
+    connected: boolean;
+    accountLabel?: string;
+    connectedAt?: string;
+    /** Older servers omit it: treat as `oauth`. */
+    authKind?: 'oauth' | 'api_key';
+}
+export interface ListConnectorsInput {
+    /** Case-insensitive substring of the display name. */
+    q?: string;
+    category?: string;
+    status?: 'connected' | 'available' | 'pending';
+}
+export interface ConnectorFacets {
+    total: number;
+    status: {
+        connected: number;
+        available: number;
+        pending: number;
+    };
+    categories: Array<{
+        name: string;
+        count: number;
+    }>;
+}
+export interface AuthorizeConnectorInput {
+    /** Where the platform sends the browser after the provider consent. */
+    postAuthRedirect: string;
+    /** Shopify only. */
+    shop?: string;
+}
+export type AppStatus = 'draft' | 'published';
+/** `GET /apps?tenantId=` item (secrets only as prefixes). */
+/** PDK-CONSOLE G2. Publication rules an App declares as data (server:
+ *  identity/domain/app-template-policy.ts). `*` wildcards, case-insensitive. */
+export interface AppTemplatePolicy {
+    requireUsesCatalog?: boolean;
+    forbiddenToolNamePatterns?: string[];
+    forbiddenConnectorIds?: string[];
+    forbiddenSecretKeyPatterns?: string[];
+    blockFixedValuesInPrompts?: boolean;
+}
+/** Editable fields of `PATCH /apps/:id` (server UpdateAppDto). `templatePolicy` is owner-only; null clears. */
+export interface UpdateAppInput {
+    name?: string;
+    description?: string | null;
+    logoUrl?: string | null;
+    coverUrl?: string | null;
+    content?: string | null;
+    templatePolicy?: AppTemplatePolicy | null;
+}
+export interface AppSummary {
+    id: string;
+    name: string;
+    description?: string | null;
+    content?: string | null;
+    logoUrl?: string | null;
+    coverUrl?: string | null;
+    /** PDK-CONSOLE G2. Publication rules for templates published under the App; null = none. */
+    templatePolicy?: AppTemplatePolicy | null;
+    status: AppStatus;
+    publicKey: string;
+    apiSecretPrefix: string;
+    publicKeyTest: string | null;
+    apiSecretTestPrefix: string | null;
+    revokedAt?: string | null;
+    lastUsedAt?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export type TemplateKind = 'agent' | 'team' | 'app';
+export type TemplateVisibility = 'system' | 'tenant' | 'public';
+export type MarketplaceStatus = 'none' | 'pending_review' | 'approved' | 'rejected';
+export type MarketplaceLocale = 'es' | 'en';
+export type MarketplaceCategoryGroup = 'industry' | 'use_case';
+export declare const CONFIG_FIELD_TYPES: readonly ["text", "longtext", "phone", "address", "url", "google_sheet", "drive_file", "hours", "delivery", "payments"];
+/** Known types; the server may add more, hence `string` in the wire field. */
+export type ConfigFieldType = (typeof CONFIG_FIELD_TYPES)[number] | (string & {});
+export interface TemplateConfigField {
+    key: string;
+    label: string;
+    help?: string;
+    type: ConfigFieldType;
+    required: boolean;
+    picker?: {
+        connectorId: string;
+        resourceType: string;
+    };
+}
+export interface TemplateCategoryRef {
+    slug: string;
+    group: MarketplaceCategoryGroup;
+    primary: boolean;
+    active: boolean;
+    labels: Record<string, string>;
+}
+export interface MarketplaceCategory {
+    slug: string;
+    group: MarketplaceCategoryGroup;
+    labels: Record<string, string>;
+    icon?: string | null;
+    active: boolean;
+}
+/** PDK-CONSOLE-a. The App a template is published under (its brand). */
+export interface TemplatePublisher {
+    appId: string;
+    name: string;
+    logoUrl: string | null;
+}
+/** PDK-CONSOLE-a. The workspace (and person) that authored a template. */
+export interface TemplateAuthor {
+    tenantId: string;
+    tenantName: string;
+    userDisplayName?: string;
+}
+/** A template row (summary + payload where the route returns it). */
+export interface Template {
+    id: string;
+    tenantId: string | null;
+    kind: TemplateKind;
+    name: string;
+    description?: string | null;
+    icon?: string | null;
+    /** @deprecated legacy free text; use `categories`. */
+    category?: string | null;
+    tags?: string[] | null;
+    payload?: Record<string, unknown>;
+    requiresConnectors?: string[] | null;
+    requiresSecrets?: string[] | null;
+    requiresConfig?: string[] | null;
+    configSchema?: TemplateConfigField[] | null;
+    visibility: TemplateVisibility;
+    shareToken?: string;
+    installedFromTemplateId?: string | null;
+    /** The team the template is edited through (its copy). */
+    sourceTeamId?: string | null;
+    installsCount: number;
+    currentVersion: number;
+    createdByUserId?: string | null;
+    priceCents?: number | null;
+    marketplaceStatus?: MarketplaceStatus;
+    sourceAppId?: string;
+    appActive?: boolean;
+    logoUrl?: string | null;
+    coverUrl?: string | null;
+    locale?: MarketplaceLocale | null;
+    guideMd?: string | null;
+    categories?: TemplateCategoryRef[];
+    /** PDK-CONSOLE-a. Optional so an older platform still type-checks. */
+    publisher?: TemplatePublisher | null;
+    author?: TemplateAuthor | null;
+    /** Raw publisher App id; null = published by the workspace. */
+    publisherAppId?: string | null;
+    /** PDK-CONSOLE G4. On `GET /templates/:id`, for the template's workspace members and platform admins only. */
+    installs?: TemplateInstallStats;
+    createdAt: string;
+    updatedAt: string;
+}
+/** PDK-CONSOLE G4. `total` cumulative; `byVersion` counts installs that exist now (`version: null` = pre-versioning). */
+export interface TemplateInstallStats {
+    total: number;
+    active: number;
+    byVersion: Array<{
+        version: number | null;
+        count: number;
+    }>;
+}
+/** `GET /templates/:id/policy-check`: dry run of an App's template policy (nothing is written). */
+export interface TemplatePolicyCheck {
+    appId: string | null;
+    appName: string | null;
+    version: number;
+    issues: TeamPublicationIssue[];
+    canPublish: boolean;
+}
+export interface ListTemplatesInput {
+    kind?: TemplateKind;
+    q?: string;
+    /** Linked to ANY of these category slugs. */
+    categories?: string[];
+    primaryCategory?: string;
+    /** PDK-CONSOLE G1. Session `GET /templates` only: rows published under this App. */
+    publisherAppId?: string;
+    /** 1-200. */
+    limit?: number;
+}
+export interface SaveTemplateInput {
+    name?: string;
+    description?: string;
+    icon?: string;
+    category?: string;
+    tags?: string[];
+    visibility?: TemplateVisibility;
+    /** Fields for the prompts' `{{config:KEY}}` tokens (400 `invalid_config_schema` if malformed). */
+    configSchema?: TemplateConfigField[];
+    /** PDK-CONSOLE G1. App to publish under (live App; owner/admin only); null clears; omitted keeps.
+     *  400 `publisher_app_not_found` / `publisher_app_not_live` / `invalid_publisher_app_id`,
+     *  `publisher_policy_violation` (all 400; `ApiError.details.issues`). */
+    publisherAppId?: string | null;
+}
+/** Body of `PATCH /templates/:id`: metadata + listing, applied at once. */
+export interface TemplateListingPatch {
+    name?: string;
+    description?: string;
+    icon?: string;
+    tags?: string[];
+    visibility?: TemplateVisibility;
+    logoUrl?: string | null;
+    coverUrl?: string | null;
+    guideMd?: string | null;
+    locale?: MarketplaceLocale | null;
+    categories?: Array<{
+        slug: string;
+        primary?: boolean;
+    }>;
+    /** PDK-CONSOLE G1. See {@link SaveTemplateInput.publisherAppId}. */
+    publisherAppId?: string | null;
+}
+export interface SignListingAssetInput {
+    kind: 'logo' | 'cover';
+    contentType: string;
+    contentLength?: number;
+}
+/** PUT the file bytes to `uploadUrl`, then PATCH the template with `publicUrl`. */
+export interface SignedUpload {
+    uploadUrl: string;
+    publicUrl: string;
+    key?: string;
+}
+export interface InstallTemplateOverrides {
+    orchestrator?: {
+        tools?: ToolPermissionInput[];
+        systemPrompt?: string;
+    };
+    /** Matched by the slug inside the template payload. */
+    members?: Array<{
+        sourceSlug: string;
+        tools?: ToolPermissionInput[];
+        systemPrompt?: string;
+    }>;
+}
+export interface InstallTemplateInput {
+    name?: string;
+    overrides?: InstallTemplateOverrides;
+}
+export interface TemplateInstallResult {
+    kind: TemplateKind;
+    agentId: string | null;
+    agentSlug: string | null;
+    teamId: string | null;
+    teamSlug: string | null;
+    requiresConnectors: string[];
+    requiresSecrets: string[];
+    requiresConfig?: string[];
+}
+export type ReadinessStatus = 'ready' | 'needs_setup' | 'blocked';
+export interface ToolReadiness {
+    name: string;
+    mode: ToolPermissionMode;
+    status: ReadinessStatus;
+    connectorId?: string;
+    connectorName?: string;
+    reason?: string;
+}
+export interface AgentReadiness {
+    slug: string;
+    name: string;
+    kind: 'standalone' | 'team-orchestrator';
+    status: ReadinessStatus;
+    tools: ToolReadiness[];
+}
+export interface TemplateReadiness {
+    templateId: string;
+    destinationTenantId: string;
+    status: ReadinessStatus;
+    agents: AgentReadiness[];
+    connectors: Array<{
+        connectorId: string;
+        connectorName: string;
+        status: ReadinessStatus;
+        reason?: string;
+    }>;
+    secrets: Array<{
+        key: string;
+        status: 'ready' | 'needs_setup';
+    }>;
+    config?: Array<{
+        key: string;
+        label: string;
+        type: ConfigFieldType;
+        required: boolean;
+        status: 'ready' | 'needs_setup';
+    }>;
+    notes: string[];
+}
+/** Old-style published version row (`GET /templates/:id/versions`). */
+export interface TemplateVersionRow {
+    id: string;
+    templateId: string;
+    version: number;
+    payload: Record<string, unknown>;
+    requiresConnectors?: string[] | null;
+    requiresSecrets?: string[] | null;
+    changelog?: string | null;
+    publishedByUserId?: string | null;
+    publishedAt: string;
+}
+export interface UpdatesAvailable {
+    agents: Array<{
+        agentId: string;
+        agentName: string;
+        templateId: string;
+        installedVersion: number | null;
+        currentVersion: number;
+    }>;
+    teams: Array<{
+        teamId: string;
+        teamName: string;
+        templateId: string;
+        installedVersion: number | null;
+        currentVersion: number;
+    }>;
+}
+export interface UpdateFromTemplateResult {
+    agentId?: string;
+    teamId?: string;
+    appliedVersion: number;
+    membersUpdated?: number;
+    membersSkipped?: number;
+    requiresConnectors?: string[];
+    requiresSecrets?: string[];
+}
+export type TemplateVersionStatus = 'draft' | 'in_review' | 'published' | 'archived';
+export interface TemplateVersionReview {
+    reviewerUserId: string;
+    decision: 'approved' | 'changes_requested';
+    comment: string | null;
+    decidedAt: string;
+}
+export interface TemplateVersionView {
+    version: number;
+    status: TemplateVersionStatus;
+    changelog: string | null;
+    authorUserId: string | null;
+    /** The author's name (never the email); absent when unknown / unnamed. */
+    authorDisplayName?: string;
+    createdAt: string;
+    submittedAt: string | null;
+    releasedAt: string | null;
+    restoredFromVersion: number | null;
+    reviews: TemplateVersionReview[];
+}
+export interface VersionHistory {
+    items: TemplateVersionView[];
+    sourceTeamId: string | null;
+    requiredApprovals: number;
+    approverUserIds: string[];
+}
+export interface TemplateSourceStatus {
+    templateId: string;
+    templateName: string;
+    kind: 'agent' | 'team';
+    publishedVersion: number;
+    open: TemplateVersionView | null;
+    unpublishedChanges: boolean;
+    approvalsNeeded: number;
+    approverUserIds: string[];
+}
+export type DiffJson = null | boolean | number | string | DiffJson[] | {
+    [k: string]: DiffJson;
+};
+export interface DiffFieldChange {
+    field: string;
+    before?: DiffJson;
+    after?: DiffJson;
+}
+export interface VersionDiff {
+    same: boolean;
+    team: DiffFieldChange[];
+    agents: Array<{
+        key: string;
+        name: string;
+        role: 'orchestrator' | 'member';
+        status: 'added' | 'removed' | 'changed';
+        fields: DiffFieldChange[];
+    }>;
+    config: Array<{
+        key: string;
+        label: string;
+        status: 'added' | 'removed' | 'changed';
+        fields: DiffFieldChange[];
+    }>;
+    other: DiffFieldChange[];
+}
+export interface TemplateConfigFields {
+    fields: TemplateConfigField[];
+    /** Keys referenced by `{{config:KEY}}` in the prompts. */
+    referenced: string[];
+    draftVersion: number | null;
+}
+export interface PlaygroundMetrics {
+    messages: number;
+    agentMessages: number;
+    userMessages: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalCostUsd: number;
+    totalDurationMs: number;
+    averageDurationMs: number;
+    delegationsCount: number;
+    toolCallsCount: number;
+    byAgent: Array<{
+        agentId: string;
+        messages: number;
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+        durationMs: number;
+    }>;
+}
+export interface PlaygroundRun {
+    id: string;
+    tenantId: string;
+    teamId: string;
+    name: string;
+    scenarioSlug?: string | null;
+    scenarioPrompt: string;
+    configMode?: string | null;
+    channelId: string;
+    status: 'running' | 'finalized' | 'aborted';
+    startedByUserId?: string | null;
+    startedAt: string;
+    finalizedAt?: string | null;
+    metrics?: PlaygroundMetrics | null;
+    transcript?: Array<{
+        id: string;
+        senderKind: 'user' | 'agent' | 'system';
+        senderAgentId?: string;
+        senderUserId?: string;
+        content: string;
+        createdAt: string;
+        metadata?: Record<string, unknown>;
+    }> | null;
+    notes?: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface StartPlaygroundRunInput {
+    teamId: string;
+    scenarioPrompt: string;
+    scenarioSlug?: string;
+    name?: string;
+    configMode?: string;
+    notes?: string;
+}
+export type TenantVariableKind = 'config' | 'secret';
+/** One workspace variable. `kind: 'config'` carries `value`; `kind: 'secret'`
+ *  never does: only `valueHint` (last 4 chars) once stored. */
+export interface TenantVariable {
+    key: string;
+    kind: TenantVariableKind;
+    description: string;
+    /** Plaintext. Present only for stored `config` variables. */
+    value?: string;
+    /** Last 4 characters of a stored secret. */
+    valueHint?: string;
+    configured: boolean;
+    source: 'env' | 'db' | 'vault' | 'none';
+    /** `system`: declared by code (cannot be deleted); `user`: created by an operator. */
+    managedBy: 'system' | 'user';
+    updatedAt?: string;
+    updatedByUserId?: string;
+    /** What reads it (adapters / connectors / tools); a non-empty list makes DELETE a 409. */
+    bindings: unknown[];
+    secretScope?: string;
+    tenantId?: string;
+    appId?: string;
+    sensitivity?: string;
+}
+export interface UpsertTenantVariableInput {
+    value: string;
+    kind?: TenantVariableKind;
+    description?: string;
+}
+/** `ApiError.code` of the publisher App checks on save / release / publish. */
+export type PublisherErrorCode = 'publisher_app_not_found' | 'publisher_app_not_live' | 'publisher_policy_violation' | 'invalid_publisher_app_id' | 'invalid_template_policy';
+/** `ApiError.details` of a 400 `publisher_policy_violation`. Each issue has a
+ *  stable `code` and `params` to translate (`policy_forbidden_tool`: tool,
+ *  pattern, agent; `policy_forbidden_connector`: tool, connector, agent;
+ *  `policy_forbidden_secret`: key, pattern, agent; `policy_fixed_value_in_prompt`:
+ *  kind, sample, agent; `policy_requires_catalog`: requirement). */
+export interface PublisherErrorBody {
+    code: PublisherErrorCode;
+    /** Same value as `code` (kept for back-compat). */
+    reason: PublisherErrorCode;
+    message: string;
+    issues?: TeamPublicationIssue[];
+}