Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
import { get, post, put, del, patch, postUpload } from '@/utils/request'
import type { CreatedTenantAPIKey, TenantAPIKey, TenantAPIKeyCapability } from '@/api/tenant'
export interface CreatePlatformAPIKeyPayload {
name: string
capabilities: TenantAPIKeyCapability[]
expires_at_unix?: number
}
export async function listPlatformAPIKeys(): Promise<{ success: boolean; data?: TenantAPIKey[] }> {
return await get('/api/v1/system/admin/api-keys') as unknown as { success: boolean; data?: TenantAPIKey[] }
}
export async function createPlatformAPIKey(
payload: CreatePlatformAPIKeyPayload,
): Promise<{ success: boolean; data?: CreatedTenantAPIKey }> {
return await post('/api/v1/system/admin/api-keys', payload) as unknown as {
success: boolean
data?: CreatedTenantAPIKey
}
}
export async function deletePlatformAPIKey(keyId: number): Promise<{ success: boolean }> {
return await del(`/api/v1/system/admin/api-keys/${keyId}`) as unknown as { success: boolean }
}
export interface SystemInfo {
version: string
edition?: string
commit_id?: string
build_time?: string
go_version?: string
keyword_index_engine?: string
vector_store_engine?: string
graph_database_engine?: string
minio_enabled?: boolean
db_version?: string
/** Human-readable error message when the startup migration failed.
* When non-empty, the system info view should surface a troubleshooting
* banner (see website-docs/01-getting-started/05-troubleshooting.md#database-migrations). */
db_migration_error?: string
/** Server process boot time (RFC3339, UTC). */
started_at?: string
/** Seconds since process start. */
uptime_seconds?: number
}
export interface DeploymentCapability {
supported: boolean
reason?: string
}
export interface DeploymentCapabilitiesResponse {
edition: string
capabilities: Record<string, DeploymentCapability>
}
export function getDeploymentCapabilities(): Promise<{ data: DeploymentCapabilitiesResponse }> {
return get('/api/v1/system/capabilities')
}
export interface PlaceholderDefinition {
name: string
label: string
description: string
}
export interface PromptTemplate {
id: string
name: string
description: string
content: string
user?: string
has_knowledge_base?: boolean
has_web_search?: boolean
default?: boolean
mode?: string
}
export interface PromptTemplatesConfig {
system_prompt: PromptTemplate[]
context_template: PromptTemplate[]
// Rewrite templates — each template contains both content (system) + user fields
rewrite: PromptTemplate[]
// Fallback templates — fixed responses + model fallback prompts (mode: "model")
fallback: PromptTemplate[]
generate_session_title?: PromptTemplate[]
generate_summary?: PromptTemplate[]
keywords_extraction?: PromptTemplate[]
chat_summary?: PromptTemplate[]
agent_system_prompt?: PromptTemplate[]
intent_prompts?: PromptTemplate[]
}
export function getSystemInfo(): Promise<{ data: SystemInfo }> {
return get('/api/v1/system/info')
}
export function getPromptTemplates(): Promise<{ data: PromptTemplatesConfig }> {
return get('/api/v1/tenants/kv/prompt-templates')
}
export interface ParserEngineInfo {
Name: string
Description: string
FileTypes: string[]
Available?: boolean
UnavailableReason?: string
}
/** 解析引擎配置(引擎连接参数存空间;聊天附件解析策略在智能体中配置) */
export type MinerUParseMethod = 'auto' | 'ocr' | 'txt'
export interface ParserEngineConfig {
docreader_addr?: string
docreader_transport?: string
mineru_endpoint?: string
mineru_api_key?: string
// MinerU 自建参数(协议自动识别:4.0+ 走 V1 API)
mineru_server_api_key?: string
mineru_tier?: string // flash / basic / standard / advanced,空为服务端默认
// 以下仅对 MinerU 3.x 及更早版本生效
mineru_model?: string
mineru_vlm_server_url?: string
mineru_enable_formula?: boolean | null
mineru_enable_table?: boolean | null
mineru_parse_method?: MinerUParseMethod
mineru_enable_ocr?: boolean | null
mineru_language?: string
// MinerU 云 API 参数
mineru_cloud_model?: string
mineru_cloud_enable_formula?: boolean | null
mineru_cloud_enable_table?: boolean | null
mineru_cloud_enable_ocr?: boolean | null
mineru_cloud_language?: string
// PaddleOCR-VL 自建参数
paddleocr_vl_endpoint?: string
paddleocr_vl_use_seal_recognition?: boolean | null
paddleocr_vl_use_chart_recognition?: boolean | null
// PaddleOCR-VL 云 API 参数
paddleocr_vl_cloud_token?: string
paddleocr_vl_cloud_model?: string
paddleocr_vl_cloud_use_seal_recognition?: boolean | null
paddleocr_vl_cloud_use_chart_recognition?: boolean | null
}
export interface ParserEnginesResponse {
data: ParserEngineInfo[]
docreader_addr?: string
/** 连接方式:grpc | http,由服务端环境/配置决定 */
docreader_transport?: string
connected?: boolean
}
export function getParserEngines(): Promise<ParserEnginesResponse> {
return get('/api/v1/system/parser-engines')
}
/** 使用当前填写的参数检测引擎可用性(不保存),用于填写新参数后即时测试 */
export function checkParserEngines(config: ParserEngineConfig): Promise<ParserEnginesResponse> {
return post('/api/v1/system/parser-engines/check', config)
}
export function getParserEngineConfig(): Promise<{ data: ParserEngineConfig }> {
return get('/api/v1/tenants/kv/parser-engine-config')
}
export function updateParserEngineConfig(config: ParserEngineConfig): Promise<{ data: ParserEngineConfig }> {
return put('/api/v1/tenants/kv/parser-engine-config', config)
}
export function reconnectDocReader(addr: string): Promise<ParserEnginesResponse & { msg?: string }> {
return post('/api/v1/system/docreader/reconnect', { addr })
}
// ---- 存储引擎配置(空间级,供文档/图片存储与 docreader 使用) ----
export interface StorageEngineConfig {
default_provider: string // "local" | "minio" | "cos" | "tos" | "s3" | "oss" | "ks3" | "obs"
local: { path_prefix: string }
minio: { mode: string; endpoint: string; access_key_id: string; secret_access_key: string; bucket_name: string; use_ssl: boolean; path_prefix: string }
cos: {
secret_id: string
secret_key: string
region: string
bucket_name: string
app_id: string
path_prefix: string
}
tos: {
endpoint: string
region: string
access_key: string
secret_key: string
bucket_name: string
path_prefix: string
}
s3: {
endpoint: string // optional for standard AWS S3
region: string
access_key: string // both keys empty => AWS default credential chain
secret_key: string
bucket_name: string
path_prefix: string
}
oss: {
endpoint: string
region: string
access_key: string
secret_key: string
bucket_name: string
path_prefix: string
use_temp_bucket: boolean
temp_bucket_name: string
temp_region: string
}
ks3: {
endpoint: string
region: string
access_key: string
secret_key: string
bucket_name: string
path_prefix: string
}
obs: {
endpoint: string
region: string
access_key: string
secret_key: string
bucket_name: string
path_prefix: string
}
}
export interface StorageEngineStatusItem {
name: string
allowed?: boolean
available: boolean
description: string
}
export interface GetStorageEngineStatusResponse {
engines: StorageEngineStatusItem[]
allowed_providers?: string[]
minio_env_available: boolean
}
export function getStorageEngineConfig(): Promise<{ data: StorageEngineConfig }> {
return get('/api/v1/tenants/kv/storage-engine-config')
}
export function updateStorageEngineConfig(config: StorageEngineConfig): Promise<{ data: StorageEngineConfig }> {
return put('/api/v1/tenants/kv/storage-engine-config', config)
}
export function getStorageEngineStatus(): Promise<{ data: GetStorageEngineStatusResponse }> {
return get('/api/v1/system/storage-engine-status')
}
export interface StorageCheckRequest {
provider: string // "minio" | "cos" | "tos" | "s3" | "oss" | "ks3" | "obs"
minio?: StorageEngineConfig['minio']
cos?: StorageEngineConfig['cos']
tos?: StorageEngineConfig['tos']
s3?: StorageEngineConfig['s3']
oss?: StorageEngineConfig['oss']
ks3?: StorageEngineConfig['ks3']
obs?: StorageEngineConfig['obs']
}
export interface StorageCheckResponse {
ok: boolean
message: string
bucket_created?: boolean
}
export function checkStorageEngine(req: StorageCheckRequest): Promise<{ data: StorageCheckResponse }> {
return post('/api/v1/system/storage-engine-check', req)
}
// ---- System Admin Management ----
export interface SystemAdminUser {
id: string
username: string
email: string
avatar?: string
is_active: boolean
is_system_admin: boolean
created_at: string
updated_at: string
}
/**
* Promote a user to system administrator.
*
* Identify the target either by user_id (UUID, for API clients) or
* email (supported by the backend for API clients). Backend
* accepts whichever is provided; user_id wins when both are set.
*
* Backend handler (system.go) returns the updated UserInfo directly as
* the response body — no {data: ...} wrapping. The shared axios
* interceptor in utils/request.ts unwraps response.data at the
* interceptor layer, so the resolved value here IS the UserInfo.
*
* The `as unknown as T` cast is the project-wide pattern for telling
* TS "trust me, the interceptor unwraps this" — see api/auth/index.ts
* for the same convention. A naked `Promise<T>` annotation would
* compile (sometimes — vue-tsc is inconsistent on AxiosResponse vs
* inline interface assignability) but is fragile.
*/
export interface PromoteUserToSystemAdminRequest {
/** UUID of the user to promote. Optional; supply this OR `email`. */
user_id?: string
/** Email address of the user to promote. Optional; supply this OR `user_id`. */
email?: string
}
export async function promoteUserToSystemAdmin(
req: PromoteUserToSystemAdminRequest,
): Promise<SystemAdminUser> {
const response = await post('/api/v1/system/admin/promote', req)
return response as unknown as SystemAdminUser
}
/**
* Revoke system administrator privileges from a user.
* Same wrapping convention as promoteUserToSystemAdmin.
*/
export async function revokeSystemAdmin(userId: string): Promise<SystemAdminUser> {
const response = await post('/api/v1/system/admin/revoke', { user_id: userId })
return response as unknown as SystemAdminUser
}
export interface SetUserStatusRequest {
user_id: string
is_active: boolean
}
/**
* Enable/disable a platform user account (SystemAdmin only).
* Disabling immediately revokes the target's active sessions.
*/
export async function setUserStatus(
req: SetUserStatusRequest,
): Promise<{ message: string; is_active: boolean }> {
const response = await post('/api/v1/system/admin/users/status', req)
return response as unknown as { message: string; is_active: boolean }
}
export interface ListAllUsersResponse {
users: SystemAdminUser[]
offset: number
limit: number
has_more: boolean
}
/**
* List every platform user across tenants (SystemAdmin only, paginated).
* Returns {users, offset, limit, has_more} directly (no data wrapping).
*/
export async function listAllUsers(
params?: { offset?: number; limit?: number },
): Promise<ListAllUsersResponse> {
const qs = new URLSearchParams()
if (params?.offset != null) qs.set('offset', String(params.offset))
if (params?.limit != null) qs.set('limit', String(params.limit))
const suffix = qs.toString() ? `?${qs.toString()}` : ''
const response = await get(`/api/v1/system/admin/users${suffix}`)
return response as unknown as ListAllUsersResponse
}
export interface ResetUserPasswordRequest {
email: string
new_password: string
}
/**
* Replace another user's password and revoke all of their active sessions.
* The backend route is restricted to SystemAdmin callers and rejects attempts
* to reset the caller's own password.
*/
export async function resetUserPassword(req: ResetUserPasswordRequest): Promise<{ message: string }> {
const response = await post('/api/v1/system/admin/users/reset-password', req)
return response as unknown as { message: string }
}
export interface CreateSystemUserRequest {
/** 2-50 characters. */
username: string
/** Must be a valid email address. */
email: string
/**
* Optional. Omit the key (or send null) to have the server generate a
* random password, returned exactly once in `generated_password`.
* Any provided value (including empty string) is subject to the
* password policy and can be rejected.
*/
password?: string
}
export interface CreateSystemUserResponse {
user: SystemAdminUser
/**
* Present only when the request omitted `password` (or sent null): the
* server-minted plaintext password, returned exactly once and could not
* be fetched again.
*/
generated_password?: string
}
export interface CreateSystemUserResult extends CreateSystemUserResponse {
/**
* True only when this call created the account (HTTP 201), false on the
* idempotent 200 retry (identity already existed).
*/
created: boolean
}
/**
* Provision a new local user account (SystemAdmin only).
* The backend answers 201 on create and 200 on the idempotent retry with
* the same CreateSystemUserResponse body. The status is projected onto
* `created`.
*/
export async function createSystemUser(req: CreateSystemUserRequest): Promise<CreateSystemUserResult> {
const response = await post<CreateSystemUserResponse>('/api/v1/system/admin/users/create', req)
return { ...response, created: response.$httpStatus === 201 }
}
// ---- System Settings (P1) ----
/**
* SystemSettingItem mirrors types.SystemSetting on the backend, exactly
* as the JSON API serialises it (no `data: ...` wrapping; see
* utils/request.ts:97 — the axios interceptor unwraps response.data
* project-wide). New fields here MUST also be added to backend
* types/system_setting.go.
*
* `value` is typed as `unknown` because the underlying JSONB column can
* hold an int / string / bool depending on `value_type`. Callers narrow
* via the value_type field (`'int' | 'string' | 'bool'`).
*/
export interface SystemSettingItem {
id: number
key: string
/** Raw JSON value — narrow via value_type before rendering. */
value: unknown
value_type: 'int' | 'string' | 'bool' | 'string_list'
category: string
description: string
/** P3+ — currently always false. UI may surface a "redacted" state when true. */
is_secret: boolean
/** P3+ — currently always false. UI may show "needs restart to take effect" badge when true. */
requires_restart: boolean
last_modified_by: string
/**
* Display label resolved from last_modified_by (UUID) on the server —
* username when known, email as a fallback. Empty/undefined for
* virtual rows that were never persisted; UI then falls back to the
* UUID prefix.
*/
last_modified_by_name?: string
created_at: string
updated_at: string
/**
* Allowed values for `value` when this setting is constrained. Populated by
* the service from the in-code registry; absent/empty means "free-form".
* Frontend renders a t-select instead of t-input when this is non-empty.
*/
enum?: string[]
}
/**
* List every system setting row (system-scope, not tenant-scope).
* Backend returns the array directly; we cast through `unknown` to match
* the project-wide axios contract (see utils/request.ts:97).
*/
export async function listSystemSettings(): Promise<SystemSettingItem[]> {
const response = await get('/api/v1/system/admin/settings')
return response as unknown as SystemSettingItem[]
}
/**
* Fetch a single system setting by key. Throws (via the axios interceptor)
* if the key is unknown to the registry, or if the row is not yet persisted.
*/
export async function getSystemSetting(key: string): Promise<SystemSettingItem> {
const response = await get(`/api/v1/system/admin/settings/${encodeURIComponent(key)}`)
return response as unknown as SystemSettingItem
}
/**
* Persist a new value for `key`. The backend validates the value against
* the registry-declared value_type and rejects mismatches with 400; the
* error message is surfaced via err.message (see utils/request.ts:209).
*
* Successful updates emit an audit row (action=system.setting_changed)
* carrying old/new values for forensics.
*/
export async function updateSystemSetting(
key: string,
value: unknown,
): Promise<SystemSettingItem> {
const response = await put(
`/api/v1/system/admin/settings/${encodeURIComponent(key)}`,
{ value },
)
return response as unknown as SystemSettingItem
}
/**
* Reset a system setting back to its ENV / built-in default by deleting
* the DB override row. Idempotent — resetting a key that was never
* persisted resolves successfully.
*/
export async function resetSystemSetting(key: string): Promise<void> {
await del(`/api/v1/system/admin/settings/${encodeURIComponent(key)}`)
}
/**
* Result of POST /system/admin/tenants/apply-default-storage-quota.
* `affected` is the count of tenant rows whose storage_quota was
* overwritten; `quota_bytes` is the value written.
*/
export interface ApplyDefaultStorageQuotaResult {
affected: number
quota_bytes: number
quota_gb: number
}
/**
* Apply the effective MB/GB default storage quota to every
* existing tenant. Reads the resolved setting server-side (DB > ENV >
* default), then writes that quota to every row. SystemAdmin only.
*
* Idempotent: running twice with the same setting has the same effect.
*/
export async function applyDefaultStorageQuotaToAllTenants(): Promise<ApplyDefaultStorageQuotaResult> {
const response = await post('/api/v1/system/admin/tenants/apply-default-storage-quota')
return response as unknown as ApplyDefaultStorageQuotaResult
}
// ---- Platform Audit Log (system-scope) ----
// We reuse the AuditLog / ListAuditLogParams types from the tenant
// audit-log module — the row shape is identical, only the route
// differs (tenant_id=0 rows aren't visible via the per-tenant endpoint).
// Re-exported here so SystemSettings.vue doesn't need to cross-import
// from a tenant-specific module to consume system-scope feeds.
export type {
AuditLog,
AuditAction,
AuditOutcome,
ListAuditLogParams,
ListAuditLogResponse,
} from '@/api/tenant/audit-log'
import type { ListAuditLogParams, ListAuditLogResponse } from '@/api/tenant/audit-log'
/**
* List the platform-wide audit log (system-scope, tenant_id=0).
*
* Backend: GET /api/v1/system/admin/audit-log (SystemAdmin only).
* Covers system.setting_changed / system.admin_promoted /
* system.admin_revoked etc. — events emitted by SystemAdmin actions.
*
* Cursor-paginated by descending id: the first call should pass no
* cursor, each subsequent page should pass `after_id =
* previousResponse.next_cursor` until next_cursor comes back as 0.
*/
export async function listSystemAuditLog(
params: ListAuditLogParams = {},
): Promise<ListAuditLogResponse> {
const qs = new URLSearchParams()
if (params.after_id) qs.append('after_id', String(params.after_id))
if (params.limit) qs.append('limit', String(params.limit))
if (params.action) qs.append('action', params.action)
if (params.outcome) qs.append('outcome', params.outcome)
if (params.actor) qs.append('actor', params.actor)
const tail = qs.toString()
const url = `/api/v1/system/admin/audit-log${tail ? '?' + tail : ''}`
return (await get(url)) as unknown as ListAuditLogResponse
}
// ---- Runtime queue observability (system-scope) ----
/**
* QueueStat mirrors types.QueueStat on the backend: a read-only depth
* snapshot of one asynq queue. `pool` identifies the independent worker pool;
* `weight` is the queue's scheduling weight within that pool.
* Counts follow asynq.QueueInfo semantics — `active` is the number of
* tasks currently being processed (the closest thing to "workers busy"),
* `pending` is the backlog waiting to be picked up.
*/
export interface QueueStat {
name: string
pool: string
weight: number
size: number
pending: number
active: number
scheduled: number
retry: number
archived: number
completed: number
processed: number
failed: number
paused: boolean
latency_ms: number
memory_usage_bytes: number
}
export interface RuntimeWorkerPool {
name: string
concurrency: number
queue_count: number
instances: number
cluster_capacity: number
active: number
utilization: number
}
export interface ModelRuntimeStat {
model_id: string
name: string
active: number
waiting: number
limit: number
}
/**
* Runtime queue dashboard payload. `available` is false in Lite mode
* (no Redis/asynq) — render an "unavailable in this deployment" state
* rather than an empty table. Each pool includes both configured per-process
* concurrency and live cluster capacity/active workers aggregated from asynq
* server heartbeats.
*/
export interface RuntimeQueuesResponse {
available: boolean
upstream_concurrency: number
parse_concurrency: number
wiki_concurrency: number
pools: RuntimeWorkerPool[]
queues: QueueStat[]
model_limiter_available: boolean
models: ModelRuntimeStat[]
timestamp: number
}
export type RuntimeTaskState = 'pending' | 'active' | 'scheduled' | 'retry' | 'archived' | 'completed'
export type RuntimeTaskAction = 'cancel' | 'run_now' | 'delete'
export interface RuntimeTask {
id: string
queue: string
type: string
state: RuntimeTaskState
allowed_actions: RuntimeTaskAction[]
last_error?: string
last_failed_at?: string
next_process_at?: string
started_at?: string
completed_at?: string
deadline?: string
enqueued_at?: string
retried: number
max_retry: number
is_orphaned?: boolean
worker?: string
tenant_id?: number
knowledge_base_id?: string
knowledge_id?: string
task_id?: string
source_id?: string
target_id?: string
source_kb_id?: string
target_kb_id?: string
data_source_id?: string
sync_log_id?: string
knowledge_count?: number
}
export interface RuntimeTasksResponse {
available: boolean
tasks: RuntimeTask[]
page_size: number
has_more: boolean
next_cursor?: string
}
/**
* Fetch the live asynq queue depths + worker-pool concurrency.
* Backend: GET /api/v1/system/admin/runtime/queues (SystemAdmin only).
* Returns the object directly — no {data: ...} wrapping (see
* utils/request.ts interceptor).
*/
export async function getRuntimeQueues(): Promise<RuntimeQueuesResponse> {
const response = await get('/api/v1/system/admin/runtime/queues')
return response as unknown as RuntimeQueuesResponse
}
export async function getRuntimeTasks(
queue: string,
state: RuntimeTaskState,
cursor = '',
pageSize = 20,
): Promise<RuntimeTasksResponse> {
return get(`/api/v1/system/admin/runtime/queues/${encodeURIComponent(queue)}/tasks`, {
params: { state, ...(cursor ? { cursor } : {}), page_size: pageSize },
})
}
export async function mutateRuntimeTask(
queue: string,
taskID: string,
action: RuntimeTaskAction,
): Promise<void> {
await post(
`/api/v1/system/admin/runtime/queues/${encodeURIComponent(queue)}/tasks/${encodeURIComponent(taskID)}/actions/${encodeURIComponent(action)}`,
)
}
/**
* Clear every archived (finally-failed) task in one queue in a single call.
* Only touches the archived dead-letter set — live tasks are never affected.
* Backend: DELETE /api/v1/system/admin/runtime/queues/{queue}/archived.
* Returns the object directly (no {data: ...} wrapping, see request.ts).
*/
export async function purgeArchivedRuntimeTasks(
queue: string,
): Promise<{ success: boolean; deleted: number }> {
const response = await del(
`/api/v1/system/admin/runtime/queues/${encodeURIComponent(queue)}/archived`,
)
return response as unknown as { success: boolean; deleted: number }
}
// --- Sandbox backend configuration (per workspace) ---
export interface SandboxVolumeMountConfig {
enabled: boolean
mount_path?: string
provider?: string
volume_id?: string
volume_name?: string
volume_owner_fingerprint?: string
}
export interface SandboxCubeConfig {
api_url?: string
proxy_url?: string
sandbox_domain?: string
api_key?: string
template_id?: string
http_timeout_sec?: number
cube_sandbox_ttl_seconds?: number
dns_servers?: string[]
}
export interface SandboxE2BConfig {
api_url?: string
proxy_url?: string
sandbox_domain?: string
api_key?: string
template_id?: string
http_timeout_sec?: number
e2b_sandbox_ttl_seconds?: number
}
export interface SandboxSkillImage {
snapshot_id?: string
generation?: number
built_at?: string
base_template_id?: string
owner_fingerprint?: string
}
export interface SandboxConfig {
sandbox_type?: string
default_timeout_sec?: number
terminal_idle_disconnect_sec?: number
desktop_enabled?: boolean
allow_private_endpoints?: boolean
env_vars?: Record<string, string>
volume_mount?: SandboxVolumeMountConfig
skill_image?: SandboxSkillImage
skill_rollout?: 'next_turn' | 'new_session'
allocation_mode?: 'session' | 'user'
user_sandbox_empty_retention_days?: number
network?: SandboxNetworkPolicy
cube?: SandboxCubeConfig
e2b?: SandboxE2BConfig
docker?: SandboxDockerConfig
}
/** Docker backend: one daemon, one long-lived container per session. */
export interface SandboxDockerConfig {
image?: string
host?: string
tls_cert_path?: string
cpu_limit?: number
memory_limit_mb?: number
pids_limit?: number
network_mode?: string
runtime?: string
idle_ttl_seconds?: number
http_timeout_sec?: number
}
/** One injected credential header on a Cube L7 rule. */
export interface SandboxCubeHeaderInject {
header: string
/** Masked as '***' in responses; send the placeholder back to keep it. */
secret?: string
/** Defaults to '${SECRET}' server-side. */
format?: string
}
/** One CubeEgress L7 rule. Match fields are AND-ed; methods are OR-ed. */
export interface SandboxCubeEgressRule {
name: string
scheme?: string
sni?: string
host?: string
methods?: string[]
path?: string
/** Absent means allow. A deny rule still needs host or sni. */
deny?: boolean
audit?: string
inject?: SandboxCubeHeaderInject[]
}
/** One E2B per-host request transform. host must also be in allow_out. */
export interface SandboxE2BHostRule {
host: string
/** Values are masked as '***' in responses. */
headers?: Record<string, string>
}
/**
* Network policy for every sandbox created from this config. Absent fields
* mean egress allowed. Inbound is always credential-required:
* allow_public_inbound is accepted then ignored/cleared.
*/
export interface SandboxNetworkPolicy {
deny_egress_by_default?: boolean
/** Ignored. Inbound is always credential-required. */
allow_public_inbound?: boolean
allow_out?: string[]
deny_out?: string[]
cube_rules?: SandboxCubeEgressRule[]
e2b_host_rules?: SandboxE2BHostRule[]
}
/** `ok: null` means the probe was not executed in this run. */
export interface SandboxCheckItem {
name: string
ok: boolean | null
message?: string
/** Stable code for why a probe was skipped; localized by the caller. */
reason?: string
latency_ms?: number
}
export interface SandboxCheckResult {
ok: boolean
provider: string
checks: SandboxCheckItem[]
capabilities?: Record<string, boolean>
}
export interface SandboxTemplate {
id: string
name: string
status?: string
version?: string
image?: string
created_at?: string
updated_at?: string
standard: boolean
/** XFCE sibling of `standard`. The admin picks one ID as this config's boot target. */
desktop?: boolean
/** The provider's own explanation for a failed build, when it reports one. */
error?: string
instance_type?: string
network_type?: string
allow_internet_access?: boolean
}
export interface SandboxTemplateCatalog {
templates: SandboxTemplate[]
standard_template_id?: string
desktop_template_id?: string
provisioned: boolean
}
/** One named sandbox backend config. Credentials arrive masked. */
export interface SandboxConfigRecord {
id: string
name: string
description?: string
sandbox_type: string
config: SandboxConfig
created_at: string
updated_at: string
}
/** Create/update payload. */
export interface SandboxConfigUpsert {
name: string
description?: string
config: SandboxConfig
}
/**
* What a config currently holds. `sandbox_count` comes from the provider, so a
* non-zero value is authoritative: identity edits and deletion are refused
* until it reaches zero.
*
* `unverifiable` means the provider could not be reached, so the count is
* UNKNOWN rather than zero — never render it as "0 sandboxes".
*/
export interface SandboxInventory {
sandbox_count: number
session_ids?: string[]
agent_names?: string[]
unverifiable?: boolean
/** Shared user machines among sandbox_count, not sessions on those machines. */
user_sandbox_count?: number
}
export interface UserSandbox {
digest: string
owner_tenant_id: number
owner_id?: string
live_sessions: number
empty_since?: string
reclaim_after?: string
}
/** Sandbox backends managed as named workspace configurations. */
export const NAMED_SANDBOX_BACKEND_TYPES = ['cube', 'e2b', 'docker'] as const
export function isNamedSandboxBackend(type: string): boolean {
return (NAMED_SANDBOX_BACKEND_TYPES as readonly string[]).includes(type)
}
/** Returns every sandbox config of the workspace. No config means disabled. */
export function listSandboxConfigs(): Promise<{
data: SandboxConfigRecord[]
workspace_scripts_disabled?: boolean
}> {
return get('/api/v1/sandbox-configs') as unknown as Promise<{
data: SandboxConfigRecord[]
workspace_scripts_disabled?: boolean
}>
}
export function setSandboxWorkspacePolicy(scriptsDisabled: boolean): Promise<{
workspace_scripts_disabled: boolean
}> {
return put('/api/v1/sandbox-configs/workspace-policy', {
scripts_disabled: scriptsDisabled,
}) as unknown as Promise<{ workspace_scripts_disabled: boolean }>
}
export function createSandboxConfig(
payload: SandboxConfigUpsert,
): Promise<{ data: SandboxConfigRecord }> {
return post('/api/v1/sandbox-configs', payload) as unknown as Promise<{
data: SandboxConfigRecord
}>
}
export function getSandboxConfigById(id: string): Promise<{ data: SandboxConfigRecord }> {
return get(`/api/v1/sandbox-configs/${id}`) as unknown as Promise<{
data: SandboxConfigRecord
}>
}
export function updateSandboxConfigById(
id: string,
payload: SandboxConfigUpsert,
): Promise<{ data: SandboxConfigRecord }> {
return put(`/api/v1/sandbox-configs/${id}`, payload) as unknown as Promise<{
data: SandboxConfigRecord
}>
}
/**
* `force` only overrides an inventory the backend could not verify; it never
* overrides sandboxes the backend can actually see. Ask for it exclusively in
* response to a `sandbox_inventory_unverifiable` conflict.
*/
export function deleteSandboxConfig(id: string, force = false): Promise<void> {
const query = force ? '?force=true' : ''
return del(`/api/v1/sandbox-configs/${id}${query}`) as unknown as Promise<void>
}
export function getSandboxConfigInventory(id: string): Promise<{ data: SandboxInventory }> {
return get(`/api/v1/sandbox-configs/${id}/sandboxes`) as unknown as Promise<{
data: SandboxInventory
}>
}
export function listUserSandboxes(configId: string) {
return get<{ success: boolean; data: UserSandbox[] }>(`/api/v1/sandbox-configs/${configId}/user-sandboxes`)
}
export function releaseUserSandbox(configId: string, digest: string) {
return post<{ success: boolean }>(`/api/v1/sandbox-configs/${configId}/user-sandboxes/${digest}/release`)
}
/**
* Fetch templates using the connection currently entered in the drawer.
* `ensure_standard` starts a provider-side CLI build when that WeKnora
* template is missing. `ensure_desktop` does the same for the XFCE image, but
* the settings UI only sends it when the admin clicks Create — listing must
* not provision a desktop template as a side effect. `replace_standard` /
* `replace_desktop` rebuild the matching template so a new spec (DNS, image)
* can take effect; they require `config_id`. The returned building item can
* be polled through the same endpoint.
*/
export function querySandboxTemplates(payload: {
config: SandboxConfig
config_id?: string
ensure_standard?: boolean
replace_standard?: boolean
ensure_desktop?: boolean
replace_desktop?: boolean
}): Promise<{ data: SandboxTemplateCatalog }> {
return post('/api/v1/sandbox-configs/templates/query', payload) as unknown as Promise<{
data: SandboxTemplateCatalog
}>
}
/**
* Probe a sandbox configuration without saving it. Redacted secrets are
* resolved server-side, so pass `config_id` alongside an edited `config` to
* test unsaved changes without retyping an API key. Omit `config` to probe a
* stored config as-is.
*
* `deep` additionally creates and destroys one sandbox, which is the only way
* to validate the template ID, Cube's proxy data plane and outbound egress.
* It consumes real sandbox time.
*/
export function checkSandboxConfig(payload: {
config?: SandboxConfig
config_id?: string
deep?: boolean
}): Promise<{ data: SandboxCheckResult }> {
return post('/api/v1/system/sandbox-check', payload) as unknown as Promise<{
data: SandboxCheckResult
}>
}
/**
* The two refusals a save or a delete can hit. They mean opposite things:
* `sandboxes_still_live` says the backend counted live sandboxes, so the only
* ways forward are ending the owning sessions or creating a second config;
* `sandbox_inventory_unverifiable` says the backend is unreachable, so nothing
* could be counted — the one case a force delete may override.
*/
export type SandboxConflictCode =
| 'sandboxes_still_live'
| 'sandbox_inventory_unverifiable'
| 'skill_snapshot_blocks_template'
export interface SandboxConflict {
code: SandboxConflictCode
message?: string
/** Present for `sandboxes_still_live`; there is nothing to report otherwise. */
inventory?: SandboxInventory
}
/**
* Reads a sandbox-config conflict out of a rejected request, or returns null
* when the failure is anything else.
*
* The interceptor spreads the response body onto the rejection, so the code
* sits at `err.error.code`. Parsing it in one place keeps callers from
* hard-coding that shape — and from confusing the two conflicts, which drive
* different recovery paths in the UI.
*/
export function parseSandboxConflict(err: unknown): SandboxConflict | null {
if (typeof err !== 'object' || err === null) return null
const detail = (err as { error?: { code?: string; message?: string; data?: SandboxInventory } }).error
if (!detail || typeof detail !== 'object') return null
if (
detail.code !== 'sandboxes_still_live' &&
detail.code !== 'sandbox_inventory_unverifiable' &&
detail.code !== 'skill_snapshot_blocks_template'
) {
return null
}
return { code: detail.code, message: detail.message, inventory: detail.data }
}
// --- Agent skills installed onto a sandbox config's image ---
export type ConfigSkillStatus = 'installing' | 'ready' | 'failed' | 'removing' | 'removed'
/**
* One environment variable the skill's installer declared. `is_set` reports
* whether a workspace-wide value exists; the value itself is never returned,
* so an editor can show that something is stored but not what.
*/
export interface ConfigSkillEnv {
name: string
description?: string
required?: boolean
is_set: boolean
}
export interface ConfigSkill {
id: string
name: string
version?: string
description?: string
enabled: boolean
status: ConfigSkillStatus | string
error?: string
bundle_sha256?: string
installed_snapshot_id?: string
// Locators for this skill's most recent install conversation. Absent for
// skills installed before transcripts existed, which is how the drawer
// decides whether to offer the "view install" entry point.
install_session_id?: string
install_message_id?: string
// Present while a newer install is in flight or has failed and the sandbox
// still runs the previous version.
served?: { version?: string }
created_at: string
updated_at: string
// Absent for a skill whose installer declared nothing, which is how the
// panel decides whether to offer the environment variable editor at all.
envs?: ConfigSkillEnv[]
}
export interface ConfigSkillInstallEvent {
percent: number
stage: string
log?: string
status?: string
done: boolean
}
export function listConfigSkills(configId: string): Promise<{ data: ConfigSkill[] }> {
return get(`/api/v1/sandbox-configs/${configId}/skills`) as unknown as Promise<{ data: ConfigSkill[] }>
}
export function uploadConfigSkill(
configId: string, file: File, onProgress?: (percent: number) => void,
): Promise<{ data: { skill_id: string } }> {
const form = new FormData()
form.append('file', file)
return postUpload(`/api/v1/sandbox-configs/${configId}/skills`, form, (e: any) => {
if (e.total) onProgress?.(Math.round((e.loaded * 100) / e.total))
}, { timeout: 5 * 60 * 1000 })
}
export function installConfigSkillFromSource(
configId: string,
payload: { source: string },
): Promise<{ data: { skill_id: string } }> {
return post(`/api/v1/sandbox-configs/${configId}/skills`, payload, {
timeout: 2 * 60 * 1000,
}) as unknown as Promise<{ data: { skill_id: string } }>
}
// Retries an install from the archive the server already stores, so a failure
// that had nothing to do with the bundle does not send the operator looking
// for the original zip or registry URL.
export function reinstallConfigSkill(
configId: string,
skillId: string,
instructions = '',
): Promise<{ data: { skill_id: string } }> {
return post(
`/api/v1/sandbox-configs/${configId}/skills/${skillId}/reinstall`,
{ instructions },
) as unknown as Promise<{ data: { skill_id: string } }>
}
// Aborts an in-flight install so retry/uninstall become available.
// After a process restart the row may still say installing with nothing running.
export function stopConfigSkill(
configId: string,
skillId: string,
): Promise<{ data: ConfigSkill }> {
return post(
`/api/v1/sandbox-configs/${configId}/skills/${skillId}/stop`,
{},
) as unknown as Promise<{ data: ConfigSkill }>
}
/**
* Partial update: an absent field is left alone. `envs` names only the
* variables to write — an entry with an empty string clears the stored value
* while keeping the declaration, and undeclared names are ignored server-side.
*/
export function patchConfigSkill(
configId: string,
skillId: string,
payload: { enabled?: boolean; envs?: Record<string, string> },
): Promise<{ data: ConfigSkill }> {
return patch(`/api/v1/sandbox-configs/${configId}/skills/${skillId}`, payload) as unknown as Promise<{
data: ConfigSkill
}>
}
export function deleteConfigSkill(
configId: string,
skillId: string,
): Promise<{ data: { skill_id: string } }> {
return del(`/api/v1/sandbox-configs/${configId}/skills/${skillId}`) as unknown as Promise<{
data: { skill_id: string }
}>
}
export function getConfigSkill(
configId: string,
skillId: string,
): Promise<{ data: ConfigSkill }> {
return get(`/api/v1/sandbox-configs/${configId}/skills/${skillId}`) as unknown as Promise<{
data: ConfigSkill
}>
}
export function configSkillInstallEventsUrl(configId: string, skillId: string): string {
return `/api/v1/sandbox-configs/${configId}/skills/${skillId}/install-events`
}
// The installer agent's own transcript: its prompt, thinking, commands and
// their output, replayed from the start and then followed live. Answers 404
// once the event log has expired, which is the signal to read the durable
// message history instead.
export function configSkillTranscriptUrl(configId: string, skillId: string): string {
return `/api/v1/sandbox-configs/${configId}/skills/${skillId}/transcript`
}
export interface ConfigSkillFileEntry {
path: string
size: number
}
export interface ConfigSkillFileContent {
path: string
size: number
encoding: 'utf-8' | 'base64' | 'binary' | string
content?: string
media_type?: string
truncated?: boolean
binary?: boolean
}
export function listConfigSkillFiles(
configId: string,
skillId: string,
): Promise<{ data: ConfigSkillFileEntry[] }> {
return get(`/api/v1/sandbox-configs/${configId}/skills/${skillId}/files`) as unknown as Promise<{
data: ConfigSkillFileEntry[]
}>
}
export function getConfigSkillFile(
configId: string,
skillId: string,
path: string,
): Promise<{ data: ConfigSkillFileContent }> {
return get(`/api/v1/sandbox-configs/${configId}/skills/${skillId}/files/content`, {
params: { path },
}) as unknown as Promise<{ data: ConfigSkillFileContent }>
}
export interface SkillInstallGuidanceState {
accepting: boolean
messages: Array<{ id: string; content: string; status: 'pending' | 'injected' | 'unprocessed' }>
}
export function getConfigSkillGuidance(configId: string, skillId: string) {
return get(`/api/v1/sandbox-configs/${configId}/skills/${skillId}/guidance`) as unknown as Promise<{ data: SkillInstallGuidanceState }>
}
export function steerConfigSkill(configId: string, skillId: string, payload: {
expected_message_id: string; steer_id: string; content: string
}) {
return post(`/api/v1/sandbox-configs/${configId}/skills/${skillId}/guidance`, payload)
}