@flashbacktech/tsclient 0.4.33

package/dist/index.d.ts

@@ -0,0 +1,1953 @@
+type TokenProvider = () => string | null | Promise<string | null>;
+type UnauthorizedHandler = () => void | Promise<void>;
+
+/**
+ * Returns the org id the platform admin is currently impersonating, or
+ * undefined when not impersonating. Resolved per-request so a UI toggle
+ * takes effect on the next call without rebuilding the client. Honored
+ * by the server only for users in the configured ADMIN_ORGANIZATION;
+ * non-admins receive a 403.
+ */
+type ImpersonationProvider = () => string | undefined | Promise<string | undefined>;
+interface BaseClientOptions {
+    baseUrl: string;
+    getToken?: TokenProvider;
+    onUnauthorized?: UnauthorizedHandler;
+    fetch?: typeof fetch;
+    debug?: boolean;
+    defaultHeaders?: Record<string, string>;
+    getImpersonateOrgId?: ImpersonationProvider;
+}
+type QueryValue = string | number | boolean | string[] | null | undefined;
+type Query = Record<string, QueryValue>;
+interface RequestOptions {
+    /**
+     * Query string params. Plain object; we serialize string/number/boolean,
+     * repeat arrays, and drop undefined/null values.
+     */
+    query?: object;
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** Skip the bearer token (used for public endpoints like /user/login). */
+    skipAuth?: boolean;
+}
+declare class BaseClient {
+    readonly baseUrl: string;
+    private readonly getToken?;
+    private readonly onUnauthorized?;
+    private readonly fetchImpl;
+    private readonly debug;
+    private readonly defaultHeaders;
+    private readonly getImpersonateOrgId?;
+    constructor(options: BaseClientOptions);
+    get<T>(path: string, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, options?: RequestOptions): Promise<T>;
+    delete<T>(path: string, options?: RequestOptions): Promise<T>;
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    private buildUrl;
+}
+
+declare enum ProviderType {
+    LOCAL = "LOCAL",
+    GOOGLE = "GOOGLE",
+    MICROSOFT = "MICROSOFT",
+    GITHUB = "GITHUB",
+    WEB3_STELLAR = "WEB3_STELLAR"
+}
+declare enum AccessType {
+    READ = "READ",
+    WRITE = "WRITE",
+    ADMIN = "ADMIN"
+}
+declare enum OrgRoles {
+    USER = 0,
+    BILLING = 1,
+    WORKSPACES = 2,
+    ADMINISTRATORS = 254,
+    OWNER = 255
+}
+interface UserSummary {
+    id: string;
+    name: string;
+    lastName: string;
+    email: string;
+    orgRole?: number | null;
+}
+
+interface AuthUser {
+    id: string;
+    email: string;
+    name: string;
+    lastName?: string;
+    orgId?: string | null;
+    orgRole?: number | null;
+    provider?: string | null;
+    validated?: boolean;
+    mfaRequired?: boolean;
+}
+interface SessionTokens {
+    accessToken: string;
+    refreshToken?: string;
+    tokenId?: string;
+    expiresAt?: number;
+}
+/**
+ * Returned by login / refresh / SSO exchange. The backend may return either
+ * a fully-verified session (`accessToken` set) or a "pending MFA" challenge
+ * (`verificationTokenId` set, `accessToken` absent). Consumers branch on
+ * whether `accessToken` is present.
+ */
+interface SessionResponse extends Partial<SessionTokens> {
+    success: boolean;
+    user?: AuthUser;
+    verificationTokenId?: string;
+    message?: string;
+    error_code?: string;
+}
+interface LoginRequest {
+    email: string;
+    password: string;
+}
+interface RegisterRequest {
+    email: string;
+    password: string;
+    firstName: string;
+    lastName: string;
+    companyName?: string;
+    website?: string;
+    isBusiness?: boolean;
+    activationUid?: string;
+    activationToken?: string;
+}
+interface ActivateRequest {
+    uid: string;
+    token: string;
+    registrationInfo?: Record<string, unknown>;
+}
+interface ResetPasswordRequest {
+    token: string;
+    newPassword: string;
+}
+interface RefreshRequest {
+    refreshToken: string;
+    provider?: ProviderType;
+}
+interface ExchangeCodeRequest {
+    code: string;
+    redirectUri?: string;
+}
+interface SimpleResponse$2 {
+    success: boolean;
+    message?: string;
+    error_code?: string;
+}
+
+declare class AuthClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    login(body: LoginRequest): Promise<SessionResponse>;
+    register(body: RegisterRequest): Promise<SessionResponse>;
+    logout(refreshToken?: string): Promise<SimpleResponse$2>;
+    refresh(body: RefreshRequest): Promise<SessionResponse>;
+    activate(body: ActivateRequest): Promise<SessionResponse>;
+    requestVerification(email: string): Promise<SimpleResponse$2>;
+    requestPasswordReset(email: string): Promise<SimpleResponse$2>;
+    resetPassword(body: ResetPasswordRequest): Promise<SimpleResponse$2>;
+    exchangeGoogle(body: ExchangeCodeRequest): Promise<SessionResponse>;
+}
+
+declare enum MFAType {
+    GOOGLE_AUTH = "GOOGLE_AUTH",
+    MAGIC_LINK = "MAGIC_LINK",
+    PASSKEY = "PASSKEY"
+}
+interface MFAStatus {
+    isEnabled: boolean;
+    isRequired: boolean;
+    isEnforced: boolean;
+    enabledMethods: MFAType[];
+    primaryMethod?: MFAType | null;
+    sessionVerified: boolean;
+}
+interface MFASetupResponse {
+    success: boolean;
+    data?: {
+        mfaType: MFAType;
+        secret?: string;
+        qrCode?: string;
+        backupCodes?: string[];
+    };
+    message?: string;
+}
+interface MFAVerifySetupRequest {
+    mfaType: MFAType;
+    code?: string;
+    credential?: Record<string, unknown>;
+}
+interface MFAVerifyLoginRequest {
+    mfaType: MFAType;
+    code?: string;
+    credential?: Record<string, unknown>;
+}
+interface MFASimpleResponse {
+    success: boolean;
+    message?: string;
+    data?: unknown;
+}
+interface MFAVerifyLoginResponse {
+    success: boolean;
+    accessToken?: string;
+    refreshToken?: string;
+    tokenId?: string;
+    expiresAt?: number;
+    user?: unknown;
+    message?: string;
+    error_code?: string;
+}
+interface MagicLinkSendResponse {
+    success: boolean;
+    message?: string;
+}
+interface MagicLinkActivateRequest {
+    token: string;
+}
+
+declare class MfaClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getStatus(): Promise<MFAStatus>;
+    getMethods(): Promise<MFAType[]>;
+    setup(body: {
+        mfaType: MFAType;
+        email?: string;
+    }): Promise<MFASetupResponse>;
+    verifySetup(body: MFAVerifySetupRequest): Promise<MFASimpleResponse>;
+    enable(mfaType: MFAType): Promise<MFASimpleResponse>;
+    disable(mfaType: MFAType): Promise<MFASimpleResponse>;
+    setPrimary(mfaType: MFAType): Promise<MFASimpleResponse>;
+    sendMagicLink(): Promise<MagicLinkSendResponse>;
+    activateMagicLink(body: MagicLinkActivateRequest): Promise<MFAVerifyLoginResponse>;
+    verifyLogin(body: MFAVerifyLoginRequest): Promise<MFAVerifyLoginResponse>;
+}
+
+interface UserProfile {
+    id: string;
+    email: string;
+    name: string;
+    lastName?: string;
+    orgId?: string | null;
+    orgRole?: number | null;
+    provider?: string | null;
+    validated?: boolean;
+    mfaRequired?: boolean;
+    createdAt?: string;
+}
+interface UpdateUserRequest {
+    name?: string;
+    lastName?: string;
+    email?: string;
+    password?: string;
+    currentPassword?: string;
+}
+interface UpdateUserResponse {
+    success: boolean;
+    data?: UserProfile;
+    message?: string;
+}
+
+declare class UserClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getProfile(): Promise<UserProfile>;
+    update(body: UpdateUserRequest): Promise<UpdateUserResponse>;
+}
+
+interface Organization {
+    id: string;
+    name: string;
+    domain: string;
+    address1?: string | null;
+    address2?: string | null;
+    city?: string | null;
+    zipcode?: string | null;
+    phone?: string | null;
+    state?: string | null;
+    country?: string | null;
+    website?: string | null;
+    is_business: boolean;
+    mfaEnforced: boolean;
+    reposDisabled?: boolean;
+    allowDebug: boolean;
+}
+interface UpdateOrganizationRequest {
+    name?: string;
+    domain?: string;
+    address1?: string;
+    address2?: string;
+    city?: string;
+    zipcode?: string;
+    phone?: string;
+    state?: string;
+    country?: string;
+    website?: string;
+    is_business?: boolean;
+    mfaEnforced?: boolean;
+}
+interface OrganizationUser {
+    id: string;
+    email: string;
+    name: string;
+    lastName?: string;
+    orgRole?: number | null;
+    validated?: boolean;
+    createdAt?: string;
+}
+interface CreateOrganizationUserRequest {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    orgRole?: number;
+}
+/** Covers name, lastName, and/or role updates — all fields optional. */
+interface UpdateOrgUserRequest {
+    name?: string;
+    lastName?: string;
+    orgRole?: number;
+}
+interface AcceptInviteRequest {
+    token: string;
+    password: string;
+}
+interface SimpleOrgResponse {
+    success: boolean;
+    message?: string;
+    data?: unknown;
+}
+
+declare class OrganizationClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    get(orgId: string): Promise<Organization>;
+    update(orgId: string, body: UpdateOrganizationRequest): Promise<Organization>;
+    listUsers(): Promise<OrganizationUser[]>;
+    updateUser(userId: string, body: UpdateOrgUserRequest): Promise<SimpleOrgResponse>;
+    /** Backend currently returns 501. Surfaced for forward-compat. */
+    createUser(body: CreateOrganizationUserRequest): Promise<SimpleOrgResponse>;
+    /** Backend currently returns 501. Surfaced for forward-compat. */
+    deleteUser(userId: string): Promise<SimpleOrgResponse>;
+    /** Accept an org invite: verifies the one-time token and sets the user's password. */
+    acceptInvite(body: AcceptInviteRequest): Promise<SimpleOrgResponse>;
+    /**
+     * Platform-admin only: list every org for the impersonation picker.
+     * The server returns 403 when the caller's home org is not the
+     * configured ADMIN_ORGANIZATION; render the picker only when the
+     * authenticated user has `isPlatformAdmin === true`.
+     */
+    listAll(): Promise<Array<{
+        id: string;
+        name: string;
+        allowDebug: boolean;
+    }>>;
+    /**
+     * Platform-admin only: enable or disable the debug surface for an org.
+     * Returns the updated org entry with the new allowDebug value.
+     */
+    setAllowDebug(orgId: string, allow: boolean): Promise<{
+        id: string;
+        name: string;
+        allowDebug: boolean;
+    }>;
+}
+
+interface ProjectMember {
+    userId: string;
+    role: string;
+    user: UserSummary;
+}
+interface Project {
+    id: string;
+    name: string;
+    orgId: string;
+    default: boolean;
+    users: ProjectMember[];
+}
+interface CreateProjectRequest {
+    name: string;
+}
+interface UpdateProjectRequest {
+    name?: string;
+}
+interface AddMemberRequest {
+    userId: string;
+    role: AccessType | string;
+}
+interface UpdateMemberRoleRequest {
+    role: AccessType | string;
+}
+
+interface SimpleResponse$1 {
+    success: boolean;
+    message?: string;
+}
+declare class ProjectsClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(): Promise<Project[]>;
+    get(projectId: string): Promise<Project>;
+    create(body: CreateProjectRequest): Promise<Project>;
+    update(projectId: string, body: UpdateProjectRequest): Promise<Project>;
+    delete(projectId: string): Promise<SimpleResponse$1>;
+    addMember(projectId: string, body: AddMemberRequest): Promise<SimpleResponse$1>;
+    updateMemberRole(projectId: string, userId: string, body: UpdateMemberRoleRequest): Promise<SimpleResponse$1>;
+    removeMember(projectId: string, userId: string): Promise<SimpleResponse$1>;
+}
+
+type StorageType = 'S3' | 'GCS' | 'BLOB';
+type ModeType = 'NORMAL' | 'MIRROR';
+interface Sandbox {
+    id: string;
+    name: string;
+    storageType: string;
+    mode: string;
+    orgId: string;
+    userId: string;
+    projectId: string | null;
+    createdAt: string;
+    disabled?: boolean;
+}
+interface CreateSandboxRequest {
+    name: string;
+    projectId: string;
+    storageType?: StorageType;
+    mode?: ModeType;
+}
+interface UpdateSandboxRequest {
+    name?: string;
+}
+interface ListSandboxesQuery {
+    projectId?: string;
+}
+
+interface SimpleResponse {
+    success: boolean;
+    message?: string;
+}
+declare class SandboxesClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(query?: ListSandboxesQuery): Promise<Sandbox[]>;
+    get(sandboxId: string): Promise<Sandbox>;
+    create(body: CreateSandboxRequest): Promise<Sandbox>;
+    update(sandboxId: string, body: UpdateSandboxRequest): Promise<Sandbox>;
+    delete(sandboxId: string): Promise<SimpleResponse>;
+}
+
+type ProviderID = 'AWS' | 'BEDROCK' | 'GCP' | 'AZURE' | 'SSH' | 'GITHUB' | 'GITLAB' | 'AZURE_DEVOPS' | 'OPENAI' | 'ANTHROPIC' | 'GEMINI' | string;
+interface Credential {
+    id: string;
+    provider: ProviderID;
+    label: string;
+    metadata: Record<string, unknown>;
+    displayHint?: string;
+    createdAt: string;
+}
+interface CreateCredentialRequest {
+    provider: ProviderID;
+    label: string;
+    secret: string;
+    metadata?: Record<string, unknown>;
+    projectId: string;
+}
+interface UpdateCredentialRequest {
+    label?: string;
+    secret?: string;
+    metadata?: Record<string, unknown>;
+}
+interface ListCredentialsQuery {
+    projectId: string;
+    provider?: ProviderID;
+    capability?: 'storage' | 'ai' | 'compute' | 'vcs';
+}
+interface SandboxCredential {
+    sandboxId: string;
+    credentialId: string;
+    provider: ProviderID;
+    label: string;
+    displayHint?: string;
+    createdAt: string;
+}
+interface GatewayToken {
+    id: string;
+    sandboxId: string;
+    label: string;
+    createdAt: string;
+}
+interface CreateGatewayTokenRequest {
+    label: string;
+}
+interface CreateGatewayTokenResponse {
+    token: GatewayToken;
+    secret: string;
+}
+interface SimpleKeysResponse {
+    success: boolean;
+    message?: string;
+    data?: unknown;
+}
+
+declare class GatewayTokensClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(sandboxId: string): Promise<GatewayToken[]>;
+    /**
+     * create returns both the persisted token row and the plaintext bearer
+     * (`secret`). The bearer is shown only here; surface it to the user
+     * immediately. If they navigate away without copying, they have to
+     * delete the token and create a new one.
+     */
+    create(sandboxId: string, body: CreateGatewayTokenRequest): Promise<CreateGatewayTokenResponse>;
+    delete(sandboxId: string, tokenId: string): Promise<SimpleKeysResponse>;
+}
+
+type FieldType = 'text' | 'password' | 'number' | 'textarea' | 'pem' | 'json' | 'stringList';
+interface FieldSpec {
+    /** JSON-pointer-ish: "secret" | "metadata.<key>". */
+    path: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    /** True for fields that hold credential material — UI hides the value. */
+    secret?: boolean;
+    default?: unknown;
+    placeholder?: string;
+    help?: string;
+}
+declare const CAP_STORAGE = 1;
+declare const CAP_AI = 2;
+declare const CAP_COMPUTE = 4;
+declare const CAP_VCS = 8;
+declare const CAP_GENERAL = 255;
+interface ProviderSpec {
+    id: string;
+    displayName: string;
+    /**
+     * Bitmask of CAP_* values describing what kinds of operations this
+     * credential can drive. Sourced from the Provider master table; mirror
+     * declared inline below so the frontend can render its tabs / filters
+     * without a runtime round-trip.
+     */
+    capabilities: number;
+    fields: FieldSpec[];
+}
+declare const PROVIDER_CATALOG: Record<string, ProviderSpec>;
+declare function listProviders(): ProviderSpec[];
+declare function getProvider(id: string): ProviderSpec | undefined;
+declare function isSecretPath(path: string): boolean;
+declare function isMetadataPath(path: string): path is `metadata.${string}`;
+declare function metadataKey(path: string): string | undefined;
+/** getValueAt reads the FieldSpec.path from a separate (secret, metadata) tuple. */
+declare function getValueAt(secret: string, metadata: Record<string, unknown>, path: string): unknown;
+/** setValueAt writes to (secret, metadata). Returns the updated tuple. */
+declare function setValueAt(secret: string, metadata: Record<string, unknown>, path: string, value: unknown): {
+    secret: string;
+    metadata: Record<string, unknown>;
+};
+/**
+ * validate runs the structural checks for a credential payload. Returns
+ * an error string on failure, or null on success. Mirrors the Go-side
+ * Validate() in internal/providers/validators.go.
+ */
+declare function validate(providerId: string, label: string, secret: string, metadata: Record<string, unknown>): string | null;
+declare function computeDisplayHint(providerId: string, metadata: Record<string, unknown>): string;
+
+declare class SandboxCredentialScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(sandboxId: string): Promise<SandboxCredential[]>;
+    attach(sandboxId: string, credentialId: string): Promise<SimpleKeysResponse>;
+    detach(sandboxId: string, credentialId: string): Promise<SimpleKeysResponse>;
+}
+declare class CredentialsClient {
+    private readonly http;
+    readonly sandbox: SandboxCredentialScope;
+    readonly gatewayTokens: GatewayTokensClient;
+    constructor(http: BaseClient);
+    list(query: ListCredentialsQuery): Promise<Credential[]>;
+    create(body: CreateCredentialRequest): Promise<Credential>;
+    update(credentialId: string, body: UpdateCredentialRequest): Promise<Credential>;
+    delete(credentialId: string): Promise<SimpleKeysResponse>;
+    /**
+     * providers fetches the server-side catalog. The tsclient ships its
+     * own catalog mirror in ./providers.ts that the frontend can use
+     * synchronously; this endpoint is the runtime source of truth and
+     * picks up customer extensions added server-side without a tsclient
+     * republish.
+     */
+    providers(): Promise<ProviderSpec[]>;
+}
+
+/**
+ * Chat-mode types for the agent engine. The new SDK speaks `sandboxId` and
+ * `projectId`; the legacy `repoId` / `workspaceId` are still accepted on the
+ * scope tuple as fallbacks during the frontend transition.
+ */
+interface ChatScope {
+    orgId: string;
+    userId: string;
+    sandboxId: string;
+    projectId?: string;
+    /** @deprecated Use `sandboxId`. Carried only to ease the cutover. */
+    repoId?: string;
+    /** @deprecated Use `projectId`. Carried only to ease the cutover. */
+    workspaceId?: string;
+}
+type ChatSessionSource = 'adhoc' | 'template';
+type ChatMessageRole = 'user' | 'assistant' | 'system';
+type ChatMessageKind = 'text' | 'question' | 'answer' | 'tool_call' | 'tool_result';
+interface ChatSession {
+    id: string;
+    org_id: string;
+    workspace_id: string;
+    repo_id: string;
+    user_id: string;
+    title?: string;
+    agent_environment_id?: string;
+    source: ChatSessionSource;
+    template_id?: string;
+    /** M3 Stage 4: populated when this session was spawned by the
+     *  scheduler dispatcher firing a `ChatSchedule` row. The frontend
+     *  uses it to render the "Scheduled run" ribbon + hide the
+     *  composer. NULL on every attended session. */
+    schedule_id?: string | null;
+    /** M3 Stage 4: mirror of `schedule_id != null` — true for sessions
+     *  the scheduler created with `Loop.Unattended = true`. */
+    unattended?: boolean;
+    created_at: string;
+    updated_at: string;
+    last_message_at?: string | null;
+    /** Sum of `cost_usd_micros` across this session's `execution_receipts`.
+     *  Populated only by list endpoints; absent on single-session fetches. */
+    total_cost_usd_micros?: number | null;
+    /** Sum of prompt + completion tokens across this session's LLM calls.
+     *  Populated only by list endpoints; absent on single-session fetches. */
+    total_tokens?: number | null;
+}
+interface ChatMessage {
+    id: string;
+    conversation_id: string;
+    org_id: string;
+    repo_id: string;
+    user_id: string;
+    turn_id: string;
+    role: ChatMessageRole;
+    kind: ChatMessageKind;
+    content?: string;
+    plan_id?: string;
+    clarification_session_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+}
+interface CreateChatSessionRequest {
+    title?: string;
+    workspace_id: string;
+    repo_id: string;
+    agent_environment_id?: string;
+    source?: ChatSessionSource;
+    template_id?: string;
+}
+interface CreateChatSessionResponse {
+    conversation_id: string;
+    session: ChatSession;
+}
+interface ListChatSessionsResponse {
+    sessions: ChatSession[];
+    next_cursor?: string;
+}
+interface ListChatSessionsQuery {
+    cursor?: string;
+    limit?: number;
+}
+interface GetChatSessionResponse {
+    session: ChatSession;
+    messages: ChatMessage[];
+}
+interface PostChatMessageRequest {
+    text: string;
+    attachments?: Array<Record<string, unknown>>;
+    template_params?: Record<string, unknown>;
+    auto_approve?: boolean;
+}
+interface PostChatMessageResponse {
+    message_id: string;
+    turn_id: string;
+}
+interface AnswerChatQuestionRequest {
+    question_id: string;
+    selected_ids?: string[];
+    custom_text?: string;
+}
+interface AnswerChatQuestionResponse {
+    status: 'accepted';
+}
+/**
+ * Response from POST /chat/sessions/:id/messages/:turn_id/cancel — the
+ * Stop affordance the dashboard fires to interrupt an in-flight turn.
+ * The engine still emits a terminal `done` SSE event with
+ * status="context_cancelled" after this returns; the frontend renders a
+ * muted "Cancelled" marker on that event rather than on this response.
+ */
+interface CancelChatTurnResponse {
+    status: 'cancelling';
+    turn_id: string;
+}
+/**
+ * Body the dashboard POSTs to
+ * /chat/sessions/:id/messages/:turn_id/confirm/:tool_call_id when the
+ * user clicks approve / deny on the M3 confirmation modal. `note` is
+ * optional free-text rationale surfaced in the synthesised
+ * "DENIED:" tool result on deny so the model can see *why* the user
+ * said no.
+ *
+ * `apply_to_session` opts the user into sticky-allow: when present
+ * with decision='allow', every subsequent tool call in this chat
+ * session that classifies into the same category dispatches without
+ * re-prompting. Ignored when decision='deny'. Default: false.
+ */
+interface ConfirmChatToolCallRequest {
+    decision: 'allow' | 'deny';
+    note?: string;
+    apply_to_session?: boolean;
+}
+interface ConfirmChatToolCallResponse {
+    status: 'accepted';
+}
+/**
+ * Action categories the M3 policy engine recognises (see
+ * docs/design/chat-loop/chat-loop-m3-safety-scheduling.md §4). `read`
+ * is implicit / always allowed and never appears in a grant set —
+ * include the mutating eight in the union so the schedule editor's
+ * category multi-select can be typed.
+ */
+type ActionCategory = 'write_data' | 'create_resource' | 'delete_data' | 'destroy_resource' | 'scale_capacity' | 'modify_iam' | 'modify_network' | 'execute_runtime';
+/** Run status stamped on agent_chat_schedules.last_run_status. */
+type ChatScheduleRunStatus = 'success' | 'blocked' | 'failed' | 'running';
+/**
+ * ChatSchedule mirrors one row of agent_chat_schedules (M3 Stage 4).
+ * The scheduler dispatcher fires due rows on its tick interval and
+ * spawns an unattended chat session per firing — see ChatSession's
+ * `schedule_id` / `unattended` fields for the audit linkage.
+ */
+interface ChatSchedule {
+    id: string;
+    org_id: string;
+    workspace_id?: string;
+    repo_id: string;
+    created_by_user_id: string;
+    name: string;
+    prompt: string;
+    cron_expr: string;
+    /** IANA timezone name (e.g. "Europe/Madrid"). The cron expression
+     * resolves in this timezone — "0 9 * * *" with timezone
+     * "Europe/Madrid" fires at 09:00 Madrid time, including DST
+     * transitions. Defaults to "UTC" on the server when omitted. */
+    timezone: string;
+    /** Subset of the repo's effective category grant. `read` is implicit
+     * — empty array == read-only schedule. */
+    granted_categories: ActionCategory[];
+    enabled: boolean;
+    max_runtime_minutes: number;
+    max_consecutive_failures?: number;
+    concurrency_policy: string;
+    next_fire_at?: string;
+    last_fire_at?: string;
+    last_run_status?: ChatScheduleRunStatus;
+    consecutive_failures: number;
+    total_runs: number;
+    total_successes: number;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateChatScheduleRequest {
+    workspace_id?: string;
+    name: string;
+    prompt: string;
+    cron_expr: string;
+    /** IANA timezone (e.g. "Europe/Madrid"). Frontend should default to
+     * `Intl.DateTimeFormat().resolvedOptions().timeZone`. Server
+     * defaults to "UTC" when omitted and rejects unknown names with
+     * `invalid_timezone` (HTTP 400). */
+    timezone?: string;
+    granted_categories?: ActionCategory[];
+    /** Defaults to true on the server when omitted. */
+    enabled?: boolean;
+    max_runtime_minutes?: number;
+    max_consecutive_failures?: number;
+    concurrency_policy?: string;
+}
+interface UpdateChatScheduleRequest {
+    name?: string;
+    prompt?: string;
+    cron_expr?: string;
+    /** IANA timezone. Pass to change; omit to leave unchanged.
+     * Changing timezone alone (without cron_expr) still recomputes
+     * `next_fire_at` since the wall-clock target shifts. */
+    timezone?: string;
+    /** Pass an empty array to relax to read-only; omit to leave
+     * unchanged. */
+    granted_categories?: ActionCategory[];
+    enabled?: boolean;
+    max_runtime_minutes?: number;
+    max_consecutive_failures?: number;
+    concurrency_policy?: string;
+}
+interface ListChatSchedulesResponse {
+    schedules: ChatSchedule[];
+}
+interface ChatScheduleEnvelope {
+    schedule: ChatSchedule;
+}
+/** Response from GET /v1/agent/repos/:repo_id/schedules/:id/runs.
+ *
+ * Each entry is a full `ChatSession` row — `id` is the conversation id
+ * the SchedulesTab uses to navigate into the standard chat session
+ * viewer (which renders the unattended ribbon when `unattended` is
+ * true, which is always true for scheduled runs). */
+interface ListChatScheduleRunsResponse {
+    runs: ChatSession[];
+}
+interface ClarificationOption {
+    id: string;
+    label: string;
+    description?: string;
+}
+type ChatEventType = 'phase' | 'question' | 'plan_draft' | 'step_started' | 'step_completed' | 'step_failed' | 'step_progress' | 'narration' | 'assistant_message' | 'done' | 'session_title' | 'tool_call_started' | 'tool_call_finished' | 'llm_call_finished' | 'tool_call_confirmation_required';
+type ChatPhase = 'classifying' | 'clarifying' | 'executing' | 'answering' | 'done';
+interface ChatPhasePayload {
+    phase: ChatPhase;
+}
+interface ChatQuestionPayload {
+    question_id: string;
+    prompt: string;
+    kind: string;
+    options?: ClarificationOption[];
+    default?: string;
+    role?: string;
+}
+interface ChatStepEventPayload {
+    step_id: string;
+    status: string;
+    started_at?: string;
+    completed_at?: string;
+    error?: string;
+    description?: string;
+}
+/**
+ * Sent with `plan_draft` once per turn when the chat-loop's model calls
+ * the report_plan tool to declare a multi-step task breakdown. The
+ * dashboard renders steps as a live checklist; matching step_started /
+ * step_completed / step_failed events with step_id = "step-N" move the
+ * checklist status as the model progresses.
+ */
+interface ChatPlanDraftPayload {
+    turn_id: string;
+    steps: string[];
+    summary?: string;
+}
+/**
+ * Sent with `tool_call_started`, once per chat-loop tool dispatch BEFORE
+ * the tool runs. Pairs with `tool_call_finished` via tool_call_id.
+ */
+interface ChatToolCallStartedPayload {
+    turn_index: number;
+    tool_name: string;
+    tool_call_id: string;
+    /** Short human-readable preview of the arguments, truncated. */
+    summary: string;
+    /**
+     * Model-authored 3–10 word user-facing description of what this call
+     * accomplishes (e.g. "Listing S3 buckets"). The dashboard renders this
+     * verbatim as the live tool-call label, replacing "Calling bash".
+     * Missing / empty → renderer falls back to the tool name.
+     */
+    intent?: string;
+}
+/**
+ * Sent with `tool_call_finished`, once per chat-loop tool dispatch AFTER
+ * the tool returns.
+ */
+interface ChatToolCallFinishedPayload {
+    turn_index: number;
+    tool_name: string;
+    tool_call_id: string;
+    /** Short human-readable preview of stdout/stderr, truncated. */
+    summary: string;
+}
+/**
+ * Sent with `llm_call_finished` once per successful LLM round-trip during
+ * a chat-loop turn. The dashboard's budget badge uses this as a fast
+ * invalidation signal so the displayed spend tracks the persisted total
+ * in near real time, instead of waiting for the 30 s poll. Failed LLM
+ * calls do not emit.
+ */
+interface ChatLLMCallFinishedPayload {
+    turn_index: number;
+    model: string;
+    /** USD cost in micros (1e-6 USD) attributed to this LLM call. Zero
+     * when no pricing row matched the model — clients should still treat
+     * the event as a refetch hint. */
+    cost_delta_micros: number;
+}
+/**
+ * Sent with `tool_call_confirmation_required` when the M3 policy hook
+ * classifies a tool call into a category that is permitted at the
+ * org/workspace/repo level but is also in the chat session's
+ * `confirm_categories` set — the user wants to approve each invocation
+ * inline before the engine dispatches it. The chat loop suspends until
+ * the dashboard POSTs the user's decision to
+ * `/v1/agent/chat/sessions/:id/messages/:turn_id/confirm/:tool_call_id`
+ * (or until the 4-minute confirmer timeout elapses, which is treated as
+ * an implicit deny — safe default).
+ *
+ * Unattended (scheduled) runs never emit this event — confirm collapses
+ * to deny when no human is connected.
+ */
+interface ChatToolCallConfirmationRequiredPayload {
+    turn_index: number;
+    tool_call_id: string;
+    tool_name: string;
+    /** Truncated stringification of the tool args, suitable for the
+     * modal preview. Full args remain in the surrounding
+     * `tool_call_started` event for the debug view. */
+    args_preview: string;
+    /** One of the M3 action categories (write_data, create_resource,
+     * delete_data, destroy_resource, scale_capacity, modify_iam,
+     * modify_network, execute_runtime). */
+    category: string;
+    /** Human-readable explanation from the policy engine — e.g.
+     * "category \"delete_data\" requires inline confirmation". Rendered
+     * in the modal as a hint about *why* the agent is asking. */
+    rationale?: string;
+}
+interface ChatStepProgressPayload {
+    step_id: string;
+    message: string;
+    progress_pct?: number;
+}
+interface ChatNarrationPayload {
+    step_id?: string;
+    text: string;
+}
+interface ChatAssistantMessagePayload {
+    message_id: string;
+    content: string;
+    citations?: string[];
+}
+interface ChatDonePayload {
+    turn_id: string;
+    plan_id?: string;
+    status?: string;
+    /** LLM id the chat-loop ran this turn against (M2/I5). The badge
+     * renders this next to the spend so the user can see which model
+     * was selected by the per-repo provider resolver. Empty when the
+     * turn aborted before the resolver picked one (rare). */
+    model_used?: string;
+}
+interface ChatSessionTitlePayload {
+    title: string;
+}
+interface ChatEvent {
+    conversation_id: string;
+    turn_id: string;
+    type: ChatEventType;
+    plan_id?: string;
+    step_id?: string;
+    payload?: ChatPhasePayload | ChatQuestionPayload | ChatPlanDraftPayload | ChatStepEventPayload | ChatStepProgressPayload | ChatNarrationPayload | ChatAssistantMessagePayload | ChatDonePayload | ChatSessionTitlePayload | ChatToolCallStartedPayload | ChatToolCallFinishedPayload | ChatLLMCallFinishedPayload | ChatToolCallConfirmationRequiredPayload | unknown;
+    timestamp: string;
+    event_id?: number;
+}
+/**
+ * Per-LLM-call audit row written by the chat-loop's recorder.Record (one row
+ * per Chat.Completions.New call). Mirrors execution_receipts on the engine
+ * side. All numeric token / cost fields are nullable because they weren't
+ * tracked for failed calls or pre-migration rows.
+ */
+interface DebugReceipt {
+    id: string;
+    flow_id: string;
+    org_id: string;
+    status: string;
+    duration_ms?: number | null;
+    model_used?: string | null;
+    layer?: string;
+    operation?: string;
+    attempt_number: number;
+    error?: string | null;
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    cached_prompt_tokens?: number | null;
+    cost_usd_micros?: number | null;
+    prompt?: string | null;
+    response?: string | null;
+    created_at: string;
+}
+/**
+ * Debug surface — consolidated payload returned by
+ * `GET /api/agentengine/v1/agent/chat/sessions/:id/debug`.
+ */
+interface DebugPayload {
+    session: ChatSession | null;
+    messages: ChatMessage[] | null;
+    receipts: DebugReceipt[];
+}
+
+interface OpenChatStreamOptions {
+    scope: ChatScope;
+    conversationId: string;
+    onEvent: (event: ChatEvent) => void;
+    onError?: (err: Event) => void;
+    lastEventId?: string;
+    /** Heartbeat in ms before the polyfill considers the connection stale. Default: 60000. */
+    heartbeatTimeout?: number;
+}
+interface ChatStreamHandle {
+    close(): void;
+}
+
+declare class ChatSessionsScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    create(scope: ChatScope, body: CreateChatSessionRequest): Promise<CreateChatSessionResponse>;
+    list(scope: ChatScope, query?: ListChatSessionsQuery): Promise<ListChatSessionsResponse>;
+    get(scope: ChatScope, conversationId: string): Promise<GetChatSessionResponse>;
+    delete(scope: ChatScope, conversationId: string): Promise<void>;
+}
+declare class ChatMessagesScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    post(scope: ChatScope, conversationId: string, body: PostChatMessageRequest): Promise<PostChatMessageResponse>;
+    /**
+     * Interrupts an in-flight chat-loop turn. The engine cancels the turn's
+     * Go context and asks the sandbox service to kill any in-flight docker
+     * exec inside the per-session container (the container itself survives
+     * so the next turn keeps its filesystem state). Returns 404 when no
+     * turn matches `turnId` — covers the race where the user clicks Stop
+     * just after the turn already finished.
+     *
+     * The engine still emits a terminal `done` SSE event with
+     * status="context_cancelled" after this returns; the frontend should
+     * render its "Cancelled" marker on that event rather than on this
+     * response, so a reload mid-cancel still ends in the same UI state.
+     */
+    cancel(scope: ChatScope, conversationId: string, turnId: string): Promise<CancelChatTurnResponse>;
+    /**
+     * Deliver the user's allow/deny decision on an M3 confirmation modal
+     * (fired when the policy hook emits a
+     * `tool_call_confirmation_required` SSE event). The chat-loop has
+     * suspended waiting on this call; on allow it dispatches the tool, on
+     * deny it synthesises a "DENIED:" tool result so the model can react.
+     * Returns 404 when no pending confirmation exists for the given
+     * (turn, tool_call) — usually means the 4-minute confirmer timeout
+     * already elapsed.
+     */
+    confirmToolCall(scope: ChatScope, conversationId: string, turnId: string, toolCallId: string, body: ConfirmChatToolCallRequest): Promise<ConfirmChatToolCallResponse>;
+}
+declare class ChatQuestionsScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    answer(scope: ChatScope, conversationId: string, turnId: string, body: AnswerChatQuestionRequest): Promise<AnswerChatQuestionResponse>;
+}
+/**
+ * Debug scope — fetches the consolidated payload (session, messages) used by
+ * the dashboard Debug tab. Keyed by conversation ID.
+ */
+declare class ChatDebugScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    getByConversation(scope: ChatScope, conversationId: string): Promise<DebugPayload>;
+}
+/**
+ * Schedules scope — manages the M3 Stage 4 cron-driven prompt
+ * schedules. Repo-scoped: list / create / get / update / delete are
+ * keyed by (repo, schedule_id). The dispatcher fires due schedules
+ * server-side on its tick; the SDK only handles the CRUD surface.
+ *
+ * Endpoint shape:
+ *   GET    /v1/agent/repos/:repo_id/schedules
+ *   POST   /v1/agent/repos/:repo_id/schedules
+ *   GET    /v1/agent/repos/:repo_id/schedules/:id
+ *   PUT    /v1/agent/repos/:repo_id/schedules/:id
+ *   DELETE /v1/agent/repos/:repo_id/schedules/:id
+ */
+declare class ChatSchedulesScope {
+    private readonly http;
+    constructor(http: BaseClient);
+    private repoPath;
+    list(scope: ChatScope): Promise<ListChatSchedulesResponse>;
+    create(scope: ChatScope, body: CreateChatScheduleRequest): Promise<ChatScheduleEnvelope>;
+    get(scope: ChatScope, scheduleId: string): Promise<ChatScheduleEnvelope>;
+    update(scope: ChatScope, scheduleId: string, body: UpdateChatScheduleRequest): Promise<ChatScheduleEnvelope>;
+    delete(scope: ChatScope, scheduleId: string): Promise<{
+        status: 'deleted';
+    }>;
+    /**
+     * List recent chat sessions spawned by a schedule's cron tick — used
+     * by the SchedulesTab "Runs" panel to surface real audit trail
+     * instead of dumping the user into the global chat list.
+     *
+     * Each entry is a full ChatSession row; `.id` is the conversation id
+     * the dashboard navigates to (`/chat/:conversationId`). All rows are
+     * unattended (the scheduler is the only writer of `schedule_id`),
+     * which makes the chat session viewer render the "Scheduled run"
+     * ribbon and hide the composer.
+     *
+     * Server returns the 50 most-recent rows; no cursor pagination in
+     * v1 (deferred until the long-tail audit case proves real).
+     */
+    listRuns(scope: ChatScope, scheduleId: string): Promise<ListChatScheduleRunsResponse>;
+}
+declare class ChatClient {
+    private readonly http;
+    private readonly streamDeps;
+    readonly sessions: ChatSessionsScope;
+    readonly messages: ChatMessagesScope;
+    readonly questions: ChatQuestionsScope;
+    readonly debug: ChatDebugScope;
+    readonly schedules: ChatSchedulesScope;
+    constructor(http: BaseClient, streamDeps: {
+        baseUrl: string;
+        getToken?: TokenProvider;
+    });
+    openStream(options: OpenChatStreamOptions): Promise<ChatStreamHandle>;
+}
+
+interface Template {
+    id: string;
+    org_id: string;
+    workspace_id?: string;
+    repo_id?: string;
+    name: string;
+    description?: string;
+    prompt?: string;
+    blueprint?: Record<string, unknown>;
+    trust_level?: string;
+    /** AWS | GCP | AZURE — drives discovery UI (icons, etc.). */
+    cloud_provider?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateAgentTemplateRequest {
+    name: string;
+    description?: string;
+    prompt: string;
+    workspace_id?: string;
+    repo_id?: string;
+}
+interface ListAgentTemplatesQuery {
+    workspace_id?: string;
+    repo_id?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface ListAgentTemplatesResponse {
+    templates: Template[];
+    next_cursor?: string;
+}
+interface SimpleAgentResponse {
+    status?: string;
+    success?: boolean;
+    message?: string;
+}
+interface FineTuneParams {
+    [key: string]: unknown;
+}
+interface ScheduledTask {
+    id: string;
+    org_id: string;
+    template_id: string;
+    name: string;
+    cron: string;
+    timezone?: string;
+    enabled: boolean;
+    fine_tune?: FineTuneParams;
+    created_at: string;
+    updated_at: string;
+}
+interface CreateScheduledTaskRequest {
+    template_id: string;
+    name: string;
+    cron: string;
+    timezone?: string;
+    enabled?: boolean;
+    fine_tune?: FineTuneParams;
+}
+interface ListScheduledTasksQuery {
+    org_id: string;
+    template_id?: string;
+    cursor?: string;
+    limit?: number;
+}
+interface ListScheduledTasksResponse {
+    tasks: ScheduledTask[];
+    next_cursor?: string;
+}
+
+declare class TemplatesClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(query?: ListAgentTemplatesQuery): Promise<ListAgentTemplatesResponse>;
+    create(body: CreateAgentTemplateRequest): Promise<Template>;
+    delete(templateId: string): Promise<SimpleAgentResponse>;
+}
+
+declare class ScheduledTasksClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    list(query: ListScheduledTasksQuery): Promise<ListScheduledTasksResponse>;
+    create(body: CreateScheduledTaskRequest): Promise<ScheduledTask>;
+    delete(taskId: string, orgId: string): Promise<SimpleAgentResponse>;
+}
+
+interface ResourceTreeResource {
+    id: string;
+    name: string;
+    resourceProviderId: string;
+    region: string | null;
+    accessLevel: string | null;
+    isActive: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface ResourceTreeCategory {
+    name: string;
+    resources: ResourceTreeResource[];
+}
+interface ResourceTreeGrouping {
+    id: string;
+    name: string;
+    providerGroupingId: string;
+    groupingTypeId: string;
+    groupingTypeName: string;
+    level: string;
+    children: ResourceTreeGrouping[];
+    categories: ResourceTreeCategory[];
+}
+interface ResourceTreeCredential {
+    credentialId: string | null;
+    provider: string;
+    groupings: ResourceTreeGrouping[];
+}
+interface ResourceTreeResponse {
+    success: boolean;
+    repoId: string;
+    credentials: ResourceTreeCredential[];
+}
+interface ResourceTreeQuery {
+    /** Case-insensitive substring filter applied to resource leaf names. */
+    search?: string;
+    /**
+     * When false (default), default auto-provisioned network resources
+     * (e.g. AWS default VPCs/subnets, GCP "default" network) are hidden.
+     * Pass true to include them.
+     */
+    showDefault?: boolean;
+}
+/** Direction of edge traversal during the BFS expansion. */
+type SubgraphDirection = 'out' | 'in' | 'both';
+interface SubgraphRequest {
+    /** Resource ids to start the BFS from. Either this or seedNameTokens must be non-empty. */
+    seedResourceIds?: string[];
+    /** Case-insensitive substring matches against CloudResource.name. */
+    seedNameTokens?: string[];
+    /** Default 2 on the server. */
+    depth?: number;
+    /** Filter to specific edge kinds (e.g. "writes_to", "reads_from"). */
+    edgeKinds?: string[];
+    /** Filter to specific edge domains (e.g. "data", "auth"). */
+    edgeDomains?: string[];
+    /** Default "both". */
+    direction?: SubgraphDirection;
+    /** Default 80, hard cap 200. */
+    maxNodes?: number;
+}
+interface CloudResourceContainerRef {
+    id: string;
+    name: string;
+    providerGroupingId: string;
+    groupingType?: {
+        id: string;
+        providerId: string;
+        level: string;
+        name: string;
+        description: string;
+    };
+}
+interface CloudResource {
+    id: string;
+    repoId: string;
+    credentialId?: string | null;
+    providerId: string;
+    categoryName: string;
+    groupingId: string;
+    resourceProviderId: string;
+    name: string;
+    region: string;
+    accessLevel: string;
+    metadata: Record<string, unknown> | null;
+    discoveredAt: string;
+    lastSeenAt: string;
+    isActive: boolean;
+    container?: CloudResourceContainerRef | null;
+    groupingPath?: string;
+}
+/**
+ * Directed dependency edge. Reads as "src depends on dst" (delete dst,
+ * src breaks). edgeDomain is a tag set (e.g. ["data", "control"]).
+ */
+interface CloudResourceEdge {
+    id: string;
+    repoId: string;
+    srcResourceId: string;
+    dstResourceId: string;
+    edgeKind: string;
+    edgeDomain: string[];
+    attributes: Record<string, unknown> | null;
+    discoveredAt: string;
+    lastSeenAt: string;
+    isActive: boolean;
+}
+interface SubgraphResponse {
+    success: boolean;
+    nodes: CloudResource[];
+    edges: CloudResourceEdge[];
+    /** True when the BFS hit maxNodes before exhausting the requested depth. */
+    truncated: boolean;
+}
+/**
+ * One live scan-coordination row. At most one per (repoId, credentialId)
+ * at any time. Expired leases (expiresAt < now) are reclaimable by the
+ * next AcquireScanLease call — they should NOT be rendered as "active"
+ * in the UI.
+ */
+interface CloudScanLease {
+    repoId: string;
+    credentialId: string;
+    leaseId: string;
+    startedAt: string;
+    expiresAt: string;
+    /**
+     * Free-form metadata the agent passed in (regions, providers,
+     * tenant scope). The dashboard renders this verbatim when surfacing
+     * "another scan is running" notices so the user knows what's blocked.
+     */
+    scopeHint?: Record<string, unknown> | null;
+}
+/**
+ * Append-only history of completed scans. Drives the "last refreshed at"
+ * badge and the per-scope deltas (added / removed) shown next to the
+ * resource tree.
+ */
+interface CloudScanHistory {
+    id: string;
+    repoId: string;
+    credentialId: string;
+    startedAt: string;
+    endedAt: string;
+    status: 'completed' | 'partial' | 'failed' | 'expired';
+    /** The ReconcileScope that was applied, when present. */
+    scope?: ReconcileScope | null;
+    resourcesUpserted: number;
+    resourcesRemoved: number;
+    partialFailureCount: number;
+}
+/**
+ * Tells the backend "I scanned these (tenant, region) tuples to
+ * completion." The backend hard-deletes any prior resource in the listed
+ * scopes that was not in this run's payload — that's how the tree
+ * shrinks when cloud resources are torn down. Tuples with any partial /
+ * failed collector are deliberately omitted by the agent so partial
+ * scans never wipe data.
+ */
+interface ReconcileScope {
+    tuples: ReconcileTuple[];
+}
+interface ReconcileTuple {
+    /** Tenant native id (AWS account number, GCP project, Azure subscription guid). */
+    tenantLocalKey: string;
+    /** Exact region match. Honours "*" / "global" / empty for non-regional services. */
+    region: string;
+}
+/**
+ * 409 body returned by POST /repos/:repoId/scans/lease when another scan
+ * is already in flight for the same (repoId, credentialId). The frontend
+ * is expected to surface `inProgress.scopeHint` + a friendly age-elapsed
+ * label so the user knows when to retry.
+ */
+interface ScanInProgressError {
+    success: false;
+    message: string;
+    inProgress: CloudScanLease;
+}
+interface AcquireScanLeaseRequest {
+    credentialId: string;
+    /** Clamped server-side to [60, 3600]; default 2100. */
+    ttlSeconds?: number;
+    scopeHint?: Record<string, unknown>;
+}
+interface AcquireScanLeaseResponse {
+    success: true;
+    lease: CloudScanLease;
+}
+interface ListScanHistoryQuery {
+    credentialId?: string;
+    /** Clamped server-side to [1, 100]; default 20. */
+    limit?: number;
+}
+interface ListScanHistoryResponse {
+    success: boolean;
+    scans: CloudScanHistory[];
+}
+interface PeekScanLeaseResponse {
+    success: boolean;
+    /** null when no lease exists for (repoId, credentialId). */
+    lease: CloudScanLease | null;
+}
+
+declare class ResourcesClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getTree(repoId: string, query?: ResourceTreeQuery): Promise<ResourceTreeResponse>;
+    /**
+     * BFS-walks the dependency graph starting from `seedResourceIds` (or
+     * `seedNameTokens`) and returns the matching nodes + edges. Use this
+     * to render an inbound/outbound dependency view for a selected
+     * resource. The server caps the result at maxNodes (default 80,
+     * hard cap 200) and sets `truncated` when the cap was hit.
+     */
+    getSubgraph(repoId: string, request: SubgraphRequest): Promise<SubgraphResponse>;
+    /**
+     * Returns recent scan history for a repo, optionally filtered by
+     * credential. Backed by CloudScanHistory rows written when the
+     * agent's discovery orchestrator releases a lease (or when the
+     * backend's cleanup job sweeps an expired one). Use this to render
+     * "last refreshed N min ago" badges and per-scope add/remove counts
+     * next to the resource tree.
+     */
+    listScans(repoId: string, query?: ListScanHistoryQuery): Promise<ListScanHistoryResponse>;
+    /**
+     * Peeks the active scan lease (if any) for the given credential. Used
+     * by the dashboard to display a "scan in progress" badge without
+     * attempting to acquire the lease. Returns `lease: null` when no
+     * scan is running. Expired leases are returned with their stale
+     * timestamps — callers should compare `expiresAt` to `Date.now()`
+     * before treating them as active.
+     */
+    peekScanLease(repoId: string, credentialId: string): Promise<PeekScanLeaseResponse>;
+    /**
+     * Attempts to claim a scan lease. Returns the acquired lease on
+     * success. The server responds 409 with a `ScanInProgressError`-
+     * shaped body when another scan is already in flight — callers
+     * should catch the HttpError, parse the body, and surface a polite
+     * "another scan is running" notice rather than retry automatically.
+     *
+     * NOTE: routine use is the agent's job. The dashboard typically only
+     * calls peekScanLease + listScans; this method is exposed for power-
+     * user tooling and automated test harnesses.
+     */
+    acquireScanLease(repoId: string, request: AcquireScanLeaseRequest): Promise<AcquireScanLeaseResponse>;
+}
+
+interface SystemEvent {
+    id: number;
+    timestamp: string;
+    contextId: string;
+    context: string;
+    event: string;
+    orgId: string;
+    userId: string;
+    userName: string;
+    userEmail: string;
+    projectId: string | null;
+    jsonData: string | null;
+    showUnread: boolean;
+}
+interface SystemEventQuery {
+    from_timestamp?: number;
+    to_timestamp?: number;
+    contextId?: string;
+    context?: string;
+    event?: string;
+    userId?: string;
+    projectId?: string;
+    /** @deprecated use `projectId` */
+    workspaceId?: string;
+    showUnread?: boolean;
+    skip?: number;
+    take?: number;
+}
+interface SystemEventQueryResponse {
+    events: SystemEvent[];
+    total: number;
+    skip: number;
+    take: number;
+}
+interface SystemEventReadResponse {
+    success: true;
+}
+
+declare class SystemEventsClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    query(body: SystemEventQuery): Promise<SystemEventQueryResponse>;
+    markRead(eventIdOrIds: number | number[]): Promise<SystemEventReadResponse>;
+    markUnread(eventIdOrIds: number | number[]): Promise<SystemEventReadResponse>;
+}
+
+interface SubscriptionPeriod {
+    id: string;
+    name: string;
+    amount: number;
+    currency: string;
+    interval: string;
+    intervalCount?: number;
+    /** Per-period grant in USD-cents. 0 means no grant attached. */
+    creditsGrantedCents: number;
+}
+interface SubscriptionCapability {
+    key: string;
+    label?: string;
+    limit?: number | null;
+}
+interface Subscription {
+    id: string;
+    name: string;
+    description?: string;
+    periods: SubscriptionPeriod[];
+    capabilities: SubscriptionCapability[];
+    /** Plan-level 24h rolling debit cap in USD-cents. null = no cap. */
+    dailyCreditCapCents?: number | null;
+}
+interface OrgSubscription {
+    id: string;
+    subscriptionId: string;
+    subscriptionName: string;
+    status: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    cancelAt?: string | null;
+    capabilities: SubscriptionCapability[];
+}
+interface BuySubscriptionRequest {
+    subscriptionPeriodId: string;
+}
+interface BuySubscriptionResponse {
+    success: boolean;
+    checkoutUrl?: string;
+    sessionId?: string;
+    isSubscriptionChange?: boolean;
+    previousSubscription?: {
+        id: string;
+        name: string;
+    } | null;
+    isFreeSubscription?: boolean;
+    message?: string;
+}
+interface CancelSubscriptionResponse {
+    success: boolean;
+    message?: string;
+}
+interface Payment {
+    id: string;
+    status: string;
+    amount: number;
+    currency: string;
+    createdAt: string;
+    description?: string;
+}
+interface ListPaymentsResponse {
+    success: boolean;
+    data: Payment[];
+}
+/**
+ * Org credit balance — two-bucket forfeit model (billing-v1).
+ *
+ *  - permanentCreditCents:        PAYG (credit-pack) bucket. Never expires.
+ *  - subscriptionCreditCents:     Current subscription cycle. Forfeit on
+ *                                  renewal; expires at subscriptionCreditExpiresAt.
+ *  - subscriptionCreditExpiresAt: ISO-8601; null when no subscription is active.
+ *  - totalActiveCents:            Pre-computed sum = permanent +
+ *                                  (subscription if not expired). Use this
+ *                                  to drive the daily-cap progress bar
+ *                                  and "out of credits" check.
+ *
+ * Format `(value / 100).toFixed(2)` for display. Drain order is
+ * subscription bucket first, then permanent — visualise as a single
+ * pool with a small "expires soon" tag for the subscription slice.
+ *
+ * Legacy `realtimeBalance` / `pendingConsumption` / `breakdown` /
+ * `dateBalance` fields were dropped: the chat-loop debits in real-time
+ * so there is no notion of "pending".
+ */
+interface CreditBalance {
+    permanentCreditCents: number;
+    subscriptionCreditCents: number;
+    subscriptionCreditExpiresAt: string | null;
+    totalActiveCents: number;
+}
+/** Source of a credit ledger row. Matches the kind enum from migration 0017. */
+type CreditTransactionKind = 'grant_initial' | 'grant_renewal' | 'grant_pack' | 'debit_llm' | 'debit_sandbox' | 'admin_adjust';
+/** Display category for the transactions list. */
+type CreditTransactionType = 'consumption' | 'purchase' | 'grant';
+interface CreditTransaction {
+    id: string;
+    /** Signed amount in USD-cents. Negative = debit. */
+    creditAmountCents: number;
+    kind: CreditTransactionKind;
+    type: CreditTransactionType;
+    description?: string;
+    createdAt: string;
+    repoId?: string;
+    executionReceiptId?: string;
+    sandboxSessionDebitId?: string;
+    subscriptionName?: string;
+    packName?: string;
+}
+interface ListCreditsTransactionsQuery {
+    from?: string;
+    to?: string;
+    type?: string;
+    page?: number;
+    limit?: number;
+}
+interface ListCreditsTransactionsResponse {
+    success: boolean;
+    data: CreditTransaction[];
+    pagination?: {
+        total: number;
+        page: number;
+        limit: number;
+    };
+}
+/** One month's bucket of credit activity. All money values in USD-cents. */
+interface MonthlyCreditStats {
+    month: string;
+    consumptionCents: number;
+    purchasesCents: number;
+    grantsCents: number;
+    balanceCents: number;
+}
+/**
+ * Refusal reasons from POST /v1/agent/chat/sessions/:id/messages when
+ * the billing preflight rejects a turn (HTTP 402). Frontend maps these
+ * to typed toasts. Mirrors billing.Refuse* in cloud-agent.
+ */
+type ChatBillingRefuseCode = 'out_of_credits' | 'daily_cap_reached' | 'no_subscription';
+interface ChatBillingRefuseError {
+    message: string;
+    code: ChatBillingRefuseCode;
+    permanentCreditCents: number;
+    subscriptionCreditCents: number;
+    subscriptionCreditExpiresAt: string | null;
+    totalActiveCents: number;
+    dailyCapCents: number;
+    debitedLast24hCents: number;
+}
+
+declare class SubscriptionsClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    listCatalog(): Promise<Subscription[]>;
+    getMine(): Promise<OrgSubscription | null>;
+    buy(body: BuySubscriptionRequest): Promise<BuySubscriptionResponse>;
+    cancel(): Promise<CancelSubscriptionResponse>;
+    listPayments(): Promise<Payment[]>;
+    /** Stripe-hosted billing portal URL. */
+    portal(): Promise<{
+        url: string;
+    }>;
+}
+
+declare class CreditsClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getBalance(): Promise<CreditBalance>;
+    listTransactions(query?: ListCreditsTransactionsQuery): Promise<ListCreditsTransactionsResponse>;
+    /** Backend currently returns 501. Surfaced for forward-compat. */
+    getMonthlyStats(): Promise<MonthlyCreditStats[]>;
+}
+
+interface UsageWindow {
+    from: string;
+    to: string;
+    prompt: number;
+    completion: number;
+    cached_prompt: number;
+    total: number;
+    cost_usd_micros: number;
+    calls: number;
+}
+interface UsageBucket {
+    day: string;
+    prompt: number;
+    completion: number;
+    cached_prompt: number;
+    total: number;
+    cost_usd_micros: number;
+    calls: number;
+}
+interface UsageTotals {
+    prompt: number;
+    completion: number;
+    cached_prompt: number;
+    total: number;
+    cost_usd_micros: number;
+    calls: number;
+}
+interface UsageSummaryQuery {
+    flow_kind?: 'chat' | 'template' | 'scheduled';
+    model?: string;
+}
+interface UsageReportQuery extends UsageSummaryQuery {
+    from?: string;
+    to?: string;
+    bucket?: 'hour' | 'day';
+}
+interface UsageByModelQuery extends UsageSummaryQuery {
+    from?: string;
+    to?: string;
+}
+interface UsageSummaryResponse {
+    windows: Record<'24h' | '7d' | '30d', UsageWindow>;
+}
+interface UsageReportResponse {
+    from: string;
+    to: string;
+    bucket: 'hour' | 'day';
+    rows: UsageBucket[];
+    totals: UsageTotals;
+}
+interface UsageByModelRow {
+    model: string;
+    prompt: number;
+    completion: number;
+    cached_prompt: number;
+    total: number;
+    cost_usd_micros: number;
+    calls: number;
+}
+interface UsageByModelResponse {
+    from: string;
+    to: string;
+    rows: UsageByModelRow[];
+}
+interface GetUsageSummaryQuery {
+    org_id: string;
+    from?: string;
+    to?: string;
+    template_id?: string;
+}
+interface UsageSummary {
+    window: {
+        from: string;
+        to: string;
+    };
+    totals: {
+        flows: number;
+        successful: number;
+        failed: number;
+        cost_usd: number;
+        tokens_in: number;
+        tokens_out: number;
+    };
+}
+interface GetUsageSummaryResponse {
+    summary: UsageSummary;
+}
+
+declare class UsageClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getSummary(query: GetUsageSummaryQuery): Promise<GetUsageSummaryResponse>;
+    org(query?: UsageSummaryQuery): Promise<UsageSummaryResponse>;
+    project(projectId: string, query?: UsageSummaryQuery): Promise<UsageSummaryResponse>;
+    sandbox(sandboxId: string, query?: UsageSummaryQuery): Promise<UsageSummaryResponse>;
+    chat(chatId: string, query?: UsageSummaryQuery): Promise<UsageSummaryResponse>;
+    orgReport(query?: UsageReportQuery): Promise<UsageReportResponse>;
+    projectReport(projectId: string, query?: UsageReportQuery): Promise<UsageReportResponse>;
+    sandboxReport(sandboxId: string, query?: UsageReportQuery): Promise<UsageReportResponse>;
+    chatReport(chatId: string, query?: UsageReportQuery): Promise<UsageReportResponse>;
+    orgByModel(query?: UsageByModelQuery): Promise<UsageByModelResponse>;
+    projectByModel(projectId: string, query?: UsageByModelQuery): Promise<UsageByModelResponse>;
+    sandboxByModel(sandboxId: string, query?: UsageByModelQuery): Promise<UsageByModelResponse>;
+    chatByModel(chatId: string, query?: UsageByModelQuery): Promise<UsageByModelResponse>;
+}
+
+type BudgetScope = 'org' | 'workspace' | 'repo' | 'chat';
+interface OrgBudget {
+    id: string;
+    org_id: string;
+    daily_limit: number;
+    monthly_limit: number;
+    tokens_today: number;
+    tokens_month: number;
+    daily_cost_limit_usd_micros: number;
+    monthly_cost_limit_usd_micros: number;
+    cost_today_usd_micros: number;
+    cost_month_usd_micros: number;
+    chat_session_cost_limit_usd_micros: number;
+    reset_day_at: string;
+    reset_month_at: string;
+    updated_at: string;
+    /** M3 Stage 3: action categories allowed at this scope. `read` is
+     * implicit and never appears here. Lower scopes (workspace, repo,
+     * schedule) intersect with this set. */
+    granted_categories: string[];
+    /** M3 Stage 4: inheritable schedule auto-disable threshold. Null
+     * means "inherit from parent"; engine default is 5 when every
+     * level in the chain is null. */
+    max_consecutive_failures?: number;
+}
+interface ScopedBudget {
+    id: string;
+    org_id: string;
+    workspace_id?: string;
+    repo_id?: string;
+    daily_cost_limit_usd_micros: number;
+    monthly_cost_limit_usd_micros: number;
+    chat_session_cost_limit_usd_micros: number;
+    cost_today_usd_micros: number;
+    cost_month_usd_micros: number;
+    reset_day_at: string;
+    reset_month_at: string;
+    updated_at: string;
+    /** M3 Stage 3: see OrgBudget.granted_categories. Subset of parent. */
+    granted_categories: string[];
+    /** M3 Stage 4: see OrgBudget.max_consecutive_failures. */
+    max_consecutive_failures?: number;
+}
+interface ChatBudget {
+    id: string;
+    org_id: string;
+    workspace_id: string;
+    repo_id: string;
+    chat_session_id: string;
+    cost_limit_usd_micros: number;
+    cost_total_usd_micros: number;
+    created_by_user_id: string;
+    updated_at: string;
+}
+interface EffectiveChatBudget {
+    limit_usd_micros: number;
+    source: BudgetScope;
+    spent_usd_micros: number;
+}
+interface UpdateOrgBudgetRequest {
+    daily_cost_limit_usd_micros?: number;
+    monthly_cost_limit_usd_micros?: number;
+    chat_session_cost_limit_usd_micros?: number;
+    /** M3 Stage 3: replace the action-category grant set. Omit to leave
+     * unchanged; empty array relaxes to read-only. */
+    granted_categories?: string[];
+    /** M3 Stage 4: per-scope schedule auto-disable cap. Omit to leave
+     * unchanged. */
+    max_consecutive_failures?: number;
+}
+interface UpdateScopedBudgetRequest {
+    daily_cost_limit_usd_micros?: number;
+    monthly_cost_limit_usd_micros?: number;
+    chat_session_cost_limit_usd_micros?: number;
+    /** M3 Stage 3: replace the action-category grant set. Server rejects
+     * (422 grants_outside_parent) when the requested set isn't a subset
+     * of the parent scope's effective grant. */
+    granted_categories?: string[];
+    /** M3 Stage 4: per-scope schedule auto-disable cap. */
+    max_consecutive_failures?: number;
+}
+interface UpdateChatBudgetRequest {
+    cost_limit_usd_micros: number;
+}
+interface UpdateCostLimitRequest {
+    cost_limit_usd_micros: number;
+}
+declare const usdMicros: {
+    toDollars: (micros: number) => number;
+    fromDollars: (dollars: number) => number;
+};
+
+declare class BudgetsClient {
+    private readonly http;
+    constructor(http: BaseClient);
+    getOrg(): Promise<{
+        budget: OrgBudget;
+    }>;
+    updateOrg(body: UpdateOrgBudgetRequest): Promise<{
+        budget: OrgBudget;
+        message: string;
+    }>;
+    getProject(projectId: string): Promise<{
+        budget: ScopedBudget;
+    }>;
+    updateProject(projectId: string, body: UpdateScopedBudgetRequest): Promise<{
+        budget: ScopedBudget;
+        message: string;
+    }>;
+    getSandbox(sandboxId: string): Promise<{
+        budget: ScopedBudget;
+    }>;
+    updateSandbox(sandboxId: string, body: UpdateScopedBudgetRequest): Promise<{
+        budget: ScopedBudget;
+        message: string;
+    }>;
+    getChat(chatId: string): Promise<{
+        budget: ChatBudget;
+    }>;
+    updateChat(chatId: string, body: UpdateChatBudgetRequest): Promise<{
+        message: string;
+    }>;
+    getEffectiveChat(chatId: string): Promise<EffectiveChatBudget>;
+    updateTemplateCostLimit(templateId: string, body: UpdateCostLimitRequest): Promise<unknown>;
+    updateScheduleCostLimit(scheduleId: string, body: UpdateCostLimitRequest): Promise<unknown>;
+}
+
+type CloudAgentClientOptions = BaseClientOptions;
+declare class AgentEngineFacade {
+    readonly templates: TemplatesClient;
+    readonly scheduledTasks: ScheduledTasksClient;
+    constructor(templates: TemplatesClient, scheduledTasks: ScheduledTasksClient);
+}
+declare class BillingFacade {
+    readonly subscriptions: SubscriptionsClient;
+    readonly credits: CreditsClient;
+    constructor(subscriptions: SubscriptionsClient, credits: CreditsClient);
+}
+declare class CloudAgentClient {
+    readonly http: BaseClient;
+    readonly auth: AuthClient;
+    readonly mfa: MfaClient;
+    readonly user: UserClient;
+    readonly organization: OrganizationClient;
+    readonly projects: ProjectsClient;
+    readonly sandboxes: SandboxesClient;
+    readonly credentials: CredentialsClient;
+    readonly chat: ChatClient;
+    readonly agentEngine: AgentEngineFacade;
+    readonly resources: ResourcesClient;
+    readonly systemEvents: SystemEventsClient;
+    readonly billing: BillingFacade;
+    readonly usage: UsageClient;
+    readonly budgets: BudgetsClient;
+    constructor(options: CloudAgentClientOptions);
+}
+
+declare class HttpError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly errorCode: string | null;
+    readonly body: unknown;
+    constructor(status: number, statusText: string, body: unknown);
+}
+declare class NotImplementedError extends Error {
+    constructor(method: string);
+}
+
+export { type AcceptInviteRequest, AccessType, type AcquireScanLeaseRequest, type AcquireScanLeaseResponse, type ActionCategory, type ActivateRequest, type AddMemberRequest, type AnswerChatQuestionRequest, type AnswerChatQuestionResponse, type AuthUser, BaseClient, type BaseClientOptions, type BudgetScope, BudgetsClient, type BuySubscriptionRequest, type BuySubscriptionResponse, CAP_AI, CAP_COMPUTE, CAP_GENERAL, CAP_STORAGE, CAP_VCS, type CancelChatTurnResponse, type CancelSubscriptionResponse, type ChatAssistantMessagePayload, type ChatBillingRefuseCode, type ChatBillingRefuseError, type ChatBudget, type ChatDonePayload, type ChatEvent, type ChatEventType, type ChatMessage, type ChatMessageKind, type ChatMessageRole, type ChatNarrationPayload, type ChatPhase, type ChatPhasePayload, type ChatPlanDraftPayload, type ChatQuestionPayload, type ChatSchedule, type ChatScheduleEnvelope, type ChatScheduleRunStatus, type ChatScope, type ChatSession, type ChatSessionSource, type ChatSessionTitlePayload, type ChatStepEventPayload, type ChatStepProgressPayload, type ChatStreamHandle, type ChatToolCallConfirmationRequiredPayload, type ChatToolCallFinishedPayload, type ChatToolCallStartedPayload, type ClarificationOption, CloudAgentClient, type CloudAgentClientOptions, type CloudResource, type CloudResourceContainerRef, type CloudResourceEdge, type CloudScanHistory, type CloudScanLease, type ConfirmChatToolCallRequest, type ConfirmChatToolCallResponse, type CreateAgentTemplateRequest, type CreateChatScheduleRequest, type CreateChatSessionRequest, type CreateChatSessionResponse, type CreateCredentialRequest, type CreateGatewayTokenRequest, type CreateGatewayTokenResponse, type CreateOrganizationUserRequest, type CreateProjectRequest, type CreateSandboxRequest, type CreateScheduledTaskRequest, type Credential, type CreditBalance, type CreditTransaction, type CreditTransactionKind, type CreditTransactionType, type DebugPayload, type DebugReceipt, type EffectiveChatBudget, type ExchangeCodeRequest, type FieldSpec, type FieldType, type FineTuneParams, type GatewayToken, type GetChatSessionResponse, type GetUsageSummaryQuery, type GetUsageSummaryResponse, HttpError, type ImpersonationProvider, type ListAgentTemplatesQuery, type ListAgentTemplatesResponse, type ListChatScheduleRunsResponse, type ListChatSchedulesResponse, type ListChatSessionsQuery, type ListChatSessionsResponse, type ListCredentialsQuery, type ListCreditsTransactionsQuery, type ListCreditsTransactionsResponse, type ListPaymentsResponse, type ListSandboxesQuery, type ListScanHistoryQuery, type ListScanHistoryResponse, type ListScheduledTasksQuery, type ListScheduledTasksResponse, type LoginRequest, type MFASetupResponse, type MFASimpleResponse, type MFAStatus, MFAType, type MFAVerifyLoginRequest, type MFAVerifyLoginResponse, type MFAVerifySetupRequest, type MagicLinkActivateRequest, type MagicLinkSendResponse, type ModeType, type MonthlyCreditStats, NotImplementedError, type OpenChatStreamOptions, type OrgBudget, OrgRoles, type OrgSubscription, type Organization, type OrganizationUser, PROVIDER_CATALOG, type Payment, type PeekScanLeaseResponse, type PostChatMessageRequest, type PostChatMessageResponse, type Project, type ProjectMember, type ProviderID, type ProviderSpec, ProviderType, type Query, type ReconcileScope, type ReconcileTuple, type RefreshRequest, type RegisterRequest, type RequestOptions, type ResetPasswordRequest, type ResourceTreeCategory, type ResourceTreeCredential, type ResourceTreeGrouping, type ResourceTreeResource, type ResourceTreeResponse, ResourcesClient, type Sandbox, type SandboxCredential, type ScanInProgressError, type ScheduledTask, type ScopedBudget, type SessionResponse, type SessionTokens, type SimpleAgentResponse, type SimpleKeysResponse, type SimpleOrgResponse, type SimpleResponse$2 as SimpleResponse, type StorageType, type SubgraphDirection, type SubgraphRequest, type SubgraphResponse, type Subscription, type SubscriptionCapability, type SubscriptionPeriod, type SystemEvent, type SystemEventQuery, type SystemEventQueryResponse, type SystemEventReadResponse, type Template, type TokenProvider, type UnauthorizedHandler, type UpdateChatBudgetRequest, type UpdateChatScheduleRequest, type UpdateCostLimitRequest, type UpdateCredentialRequest, type UpdateMemberRoleRequest, type UpdateOrgBudgetRequest, type UpdateOrgUserRequest, type UpdateOrganizationRequest, type UpdateProjectRequest, type UpdateSandboxRequest, type UpdateScopedBudgetRequest, type UpdateUserRequest, type UpdateUserResponse, type UsageBucket, type UsageByModelQuery, type UsageByModelResponse, type UsageByModelRow, type UsageReportQuery, type UsageReportResponse, type UsageSummary, type UsageSummaryQuery, type UsageSummaryResponse, type UsageTotals, type UsageWindow, type UserProfile, type UserSummary, computeDisplayHint, getProvider, getValueAt, isMetadataPath, isSecretPath, listProviders, metadataKey, setValueAt, usdMicros, validate };