@@ -0,0 +1,558 @@
// HWLAB Cloud Web global type declarations.
//
// 背景：web/hwlab-cloud-web 的源文件在 build 阶段会由 scripts/dist-contract.ts:buildAppBundle
// 拼接成单一虚拟模块再交给 Bun.build 打包，因此不同源文件里以模块作用域
// `let`/`const`/`function` 形式声明的标识符会在运行时相互可见，但 TypeScript
// 单独检查每个 .ts 文件时看不到这些跨文件引用。`web-types.d.ts` 用 ambient
// declaration 桥接这个语义差，让 tsc --noEmit 在严格模式下也能完成检查。
//
// 约束：app.ts/app-conversation.ts 等真正持有这些值的文件需要用同样或可赋值
// 兼容的显式类型标注同步（const el: ElMap = {...}），保证 tsc 同时校验实际
// 推断类型与本处声明的类型一致。
//
// 本文件是 .d.ts 模块（通过 export 把 type 暴露给其他 .ts 文件），但跨文件
// 的运行时标识符（el、state、initRoutes 等）用 `declare global { ... }` 包裹，
// 让它们在 tsc 的全局作用域里被识别为 ambient declaration。
// ---- Helper types ----
// WorkbenchUnknown 是 web-types.d.ts 内使用的"我们不精确知道结构"占位。
// 选择接口而不是 `any`，是为了让本声明文件本身可以过 #751 的"0 explicit
// untyped annotation"硬 gate（见 scripts/tsc-check.ts）。WorkbenchUnknown
// 仍然允许任意属性访问（因为它有索引签名），但消费方在严格模式下会被
// 提示"可能是 unknown"，从而保留类型安全的逃生路径。
export interface WorkbenchUnknown {
[ k : string ] : WorkbenchUnknown | undefined | null | number | string | boolean | bigint | symbol | object ;
}
// ---- DOM 元素表（app.ts:116 el = {...}）
export interface ElMap {
loginShell : HTMLElement
shell : HTMLElement
logoutButton : HTMLElement
leftSidebarToggle : HTMLElement
rightSidebarToggle : HTMLElement
sessionSidebarResize : HTMLElement
rightSidebarResize : HTMLElement
copySessionId : HTMLElement
routePath : HTMLElement
liveStatus : HTMLElement
liveDetail : HTMLElement
liveBuildSummary : HTMLElement
liveBuildToggle : HTMLElement
liveBuildLatest : HTMLElement
liveBuildList : HTMLElement
agentChatStatus : HTMLElement
codeAgentSummary : HTMLElement
codeAgentSummaryIcon : HTMLElement
codeAgentSummaryLabel : HTMLElement
codeAgentSummaryCapability : HTMLElement
codeAgentSummaryTrace : HTMLElement
codeAgentSummaryDetail : HTMLElement
sessionTabs : HTMLElement
sessionCreate : HTMLButtonElement
sessionDelete : HTMLButtonElement
sessionModelChannel : HTMLElement
sessionStatus : HTMLElement
conversationList : HTMLElement
gateSourceStatus : HTMLElement
gateStatusFilter : HTMLSelectElement
gateSearch : HTMLInputElement
gateRefresh : HTMLElement
gateReviewBody : HTMLElement
skillStatus : HTMLElement
skillRefresh : HTMLElement
skillUploadForm : HTMLFormElement
skillUploadInput : HTMLInputElement
skillUploadButton : HTMLElement
skillAssembly : HTMLElement
skillList : HTMLElement
skillDetailTitle : HTMLElement
skillTree : HTMLElement
skillPreview : HTMLElement
commandForm : HTMLFormElement
commandInput : HTMLTextAreaElement
codeAgentProviderProfile : HTMLSelectElement
codeAgentTimeout : HTMLSelectElement
gatewayShellTimeout : HTMLSelectElement
commandSend : HTMLElement
commandClear : HTMLElement
devicePodSelect : HTMLSelectElement
devicePodStatusTag : HTMLElement
devicePodSummary : HTMLElement
devicePodId : HTMLElement
devicePodTarget : HTMLElement
devicePodProfile : HTMLElement
devicePodFreshness : HTMLElement
devicePodInterfaces : HTMLElement
deviceEventFollow : HTMLButtonElement
deviceEventJump : HTMLButtonElement
deviceEventScroll : HTMLElement
deviceEventText : HTMLElement
deviceDetailDialog : HTMLDialogElement
deviceDetailTitle : HTMLElement
deviceDetailBody : HTMLElement
helpContent : HTMLElement
helpStatus : HTMLElement
}
// ---- State shape（ ）
export interface WorkbenchState {
conversationId : string
sessionId : string
threadId : string
activeTraceId : string
workspaceId : string
workspaceRevision : number
workspaceUpdatedAt : string
codeAgentAvailability : WorkbenchCodeAgentAvailability
chatMessages : WorkbenchChatMessage [ ] ;
activeSessionKey : string
traceStreams : Map < string , WorkbenchUnknown > ;
traceDetailsOpen : Map < string , boolean > ;
conversationRenderVersion : number ;
conversationScrollUserActiveUntil : number ;
conversationScrollPosition : { top : number ; left : number } ;
traceScrollPositions : Map < string , { top : number ; left : number } > ;
traceScrollPinnedToBottom : Map < string , boolean > ;
traceScrollUserActiveUntil : Map < string , number > ;
traceBodyScrollPositions : Map < string , { top : number ; left : number } > ;
traceBodyScrollUserActiveUntil : Map < string , number > ;
traceProgrammaticScrollWrites : number ;
fullTraceReplayInFlight : Set < string > ;
resultReconciliationInFlight : Set < string > ;
canceledTraces : Set < string > ;
currentRequest : WorkbenchChatRequest
sessionStatus : string
sessionList : WorkbenchSessionListState ;
chatPending : boolean ;
liveSurface : WorkbenchLiveSurface
gateDiagnostics : WorkbenchGateDiagnosticsState ;
skills : WorkbenchSkillsState ;
devicePod : WorkbenchDevicePodState ;
layout : WorkbenchLayoutState ;
}
export type WorkbenchChatMessageRole = "user" | "agent" | "system" ;
export type WorkbenchChatMessageStatus =
| "sent"
| "running"
| "completed"
| "failed"
| "canceled"
| "blocked"
| "timeout"
| string ;
export interface WorkbenchChatMessage {
id : string ;
role : WorkbenchChatMessageRole ;
title : string ;
text : string ;
status : WorkbenchChatMessageStatus ;
traceId? : string ;
conversationId? : string
sessionId? : string
threadId? : string
retryOf? : string
steerTraceId? : string ;
runnerTrace? : WorkbenchRunnerTrace ;
traceEvents? : WorkbenchTraceEvent [ ] ;
result? : WorkbenchChatResult
error ? : { message : string ; [ k : string ] : WorkbenchUnknown }
createdAt : string ;
updatedAt? : string ;
blockedReason? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchChatRequest {
traceId : string ;
conversationId : string
sessionId : string
threadId : string
messageId : string ;
input : string ;
steerTraceId? : string ;
lastActivityAt : number ;
lastActivityIso : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchCodeAgentAvailability {
status : string ;
reason? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchRunnerTrace {
traceId : string ;
sessionId? : string
threadId? : string
events : WorkbenchTraceEvent [ ] ;
result? : WorkbenchChatResult
status : string ;
startedAt : string ;
finishedAt? : string
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchTraceEvent {
ts : string ;
kind : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchChatResult {
status : string ;
text? : string ;
summary? : string ;
traceId? : string ;
sessionId? : string
threadId? : string
blockedReason? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchLiveSurface {
healthLive ? : { ok : boolean ; data? : WorkbenchUnknown ; error? : WorkbenchUnknown } ;
health ? : { ok : boolean ; data? : WorkbenchUnknown ; error? : WorkbenchUnknown } ;
restIndex ? : { ok : boolean ; data? : WorkbenchUnknown ; error? : WorkbenchUnknown } ;
adapter ? : { ok : boolean ; data? : WorkbenchUnknown ; error? : WorkbenchUnknown } ;
devicePodStatus ? : { ok : boolean ; data? : WorkbenchUnknown ; error? : WorkbenchUnknown } ;
[ k : string ] : WorkbenchUnknown ;
}
export type WorkbenchSessionListPendingAction = "create" | "switch" | "delete"
export interface WorkbenchSessionListState {
loading : boolean ;
error : string
items : WorkbenchSessionListItem [ ] ;
loadedAt : string
pendingAction : WorkbenchSessionListPendingAction ;
}
export interface WorkbenchSessionListItem {
id : string ;
title? : string ;
status? : string ;
updatedAt? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchGateDiagnosticsState {
loading : boolean ;
payload : WorkbenchUnknown ;
rows : WorkbenchUnknown [ ] ;
error : string
loadedAt : string
}
export interface WorkbenchSkillsState {
loading : boolean ;
uploadPending : boolean ;
detailLoading : boolean ;
previewLoading : boolean ;
items : WorkbenchSkillItem [ ] ;
roots : WorkbenchUnknown ;
agentRunAssembly : WorkbenchUnknown ;
selectedId : string
detail : WorkbenchUnknown ;
preview : WorkbenchUnknown ;
error : string
}
export interface WorkbenchSkillItem {
id : string ;
name? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchDevicePodState {
selectedDevicePodId : string ;
list : WorkbenchUnknown ;
status : WorkbenchUnknown ;
events : WorkbenchUnknown ;
chipId : WorkbenchUnknown ;
uart : WorkbenchUnknown ;
uartTail : WorkbenchUnknown ;
followEvents : boolean ;
unreadEvents : number ;
lastEventLineCount : number ;
eventScrollUserActiveUntil : number ;
details : Map < string , WorkbenchUnknown > ;
}
export interface WorkbenchLayoutState {
leftSidebarCollapsed : boolean ;
sessionSidebarWidth : number ;
sessionSidebarDrag : WorkbenchDragState
rightSidebarCollapsed : boolean ;
rightSidebarWidth : number ;
rightDrag : WorkbenchDragState
}
export interface WorkbenchDragState {
pointerId : number ;
startX : number ;
startWidth : number ;
[ k : string ] : WorkbenchUnknown ;
}
// ---- Workbench auth session（
export interface WorkbenchAuthUser {
id? : string
username? : string ;
displayName? : string ;
role? : string ;
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchAuthSession {
authenticated : boolean ;
mode : "server" | "local" | "auto" ;
user? : WorkbenchAuthUser
actor? : WorkbenchAuthUser
expiresAt? : string | number
[ k : string ] : WorkbenchUnknown ;
}
export interface WorkbenchWorkspacePayload {
workspaceId : string ;
revision : number ;
updatedAt : string ;
activeTraceId : string
selectedConversationId : string
selectedAgentSessionId : string
selectedDevicePodId : string ;
providerProfile? : string ;
[ k : string ] : WorkbenchUnknown ;
}
// ---- ambient global declarations（必须包裹在 declare global 内） ----
declare global {
const el : ElMap ;
const state : WorkbenchState ;
const viewIds : Set < string > ;
let rpcSequence : number ;
const workbenchAuthSession : WorkbenchAuthSession ;
const workbenchActorId : string
const SCROLL_USER_ACTIVITY_MS : number ;
const SCROLL_BOTTOM_PIN_PX : number ;
const API_TIMEOUT_MS : number ;
const LIVE_SURFACE_TIMEOUT_MS : number ;
const CODE_AGENT_SUBMIT_TIMEOUT_MS : number ;
const CODE_AGENT_CANCEL_TIMEOUT_MS : number ;
const FULL_TRACE_REPLAY_TIMEOUT_MS : number ;
const TRACE_STREAM_FALLBACK_MS : number ;
const TRACE_POLL_INTERVAL_MS : number ;
const SESSION_SIDEBAR_DEFAULT_WIDTH : number ;
const RIGHT_SIDEBAR_DEFAULT_WIDTH : number ;
const WORKBENCH_PROJECT_ID : string ;
const MESSAGE_MARKDOWN_STATUSES : readonly string [ ] ;
const CODEX_APP_SERVER_RUNNER_KIND : string ;
const CODEX_APP_SERVER_SESSION_MODE : string ;
const CODEX_APP_SERVER_IMPLEMENTATION_TYPE : string ;
const CODEX_APP_SERVER_PROTOCOL : string ;
let CODE_AGENT_TIMEOUT_MS : number ;
let GATEWAY_SHELL_TIMEOUT_MS : number ;
let CODE_AGENT_PROVIDER_PROFILE : string ;
function byId ( id : string ) : HTMLElement
function query ( selector : string ) : HTMLElement
function nonEmptyString ( value : WorkbenchUnknown , fallback? : string | null ) : string
function textOf ( value : WorkbenchUnknown ) : string ;
function shortTime ( iso : string ) : string ;
function textSpan ( text : string , className? : string ) : HTMLElement ;
function replaceChildren ( parent : Node | null , . . . children : Node [ ] ) : void ;
function firstNonEmptyString ( . . . values : WorkbenchUnknown [ ] ) : string
function toneClass ( tone : string | null | undefined ) : string ;
function initRoutes ( ) : void ;
function renderCodeAgentSummary ( ) : void ;
function renderConversation ( ) : void ;
function renderDrafts ( ) : void ;
function renderDevicePodPanel ( live : WorkbenchLiveSurface | null ) : void ;
function renderAgentChatStatus ( status : string , result? : WorkbenchChatResult | null ) : void ;
function latestChatResult ( ) : WorkbenchChatResult
function syncCommandInputHeight ( ) : void ;
function scheduleCodeAgentSessionPersist ( ) : void ;
function restoreCodeAgentSessionState ( ) : void ;
function nextProtocolId ( prefix : string ) : string ;
function currentCodeAgentStatusSummary ( ) : WorkbenchUnknown ;
function currentComposerState ( overrides? : Record < string , WorkbenchUnknown > ) : WorkbenchUnknown ;
function normalizeCodeAgentProviderProfile ( value : WorkbenchUnknown ) : string ;
function initCodeAgentTimeoutControl ( ) : void ;
function syncCodeAgentTimeoutControl ( ) : void ;
function clearActiveConversationState ( ) : void ;
function clearCodeAgentSessionState ( ) : void ;
function applyConversationToActiveSession (
conversation : WorkbenchSessionListItem ,
options ? : { quiet? : boolean }
) : void ;
function applyWorkbenchWorkspace ( workspace : WorkbenchWorkspacePayload ) : void ;
function isCodeAgentTimeoutError ( value : WorkbenchUnknown ) : boolean ;
function shouldReconcileRestoredCodeAgentResult ( message : WorkbenchChatMessage ) : boolean ;
function restoreStoredChatMessage ( message : WorkbenchUnknown ) : WorkbenchChatMessage
function restoreStoredRunnerTrace ( trace : WorkbenchUnknown ) : WorkbenchRunnerTrace
function codeAgentSessionSnapshotPayload ( ) : WorkbenchUnknown ;
function persistCodeAgentSessionState ( ) : void ;
function latestLocalCodeAgentSessionUpdatedAt ( ) : string
function persistAccountCodeAgentSessionState ( payload : WorkbenchUnknown ) : void ;
function flushAccountCodeAgentSessionState ( ) : Promise < void > ;
function hydrateAccountCodeAgentSessionState ( ) : Promise < boolean > ;
function latestTraceIdFromStoredMessages ( messages : WorkbenchChatMessage [ ] ) : string
function activeTraceIdFromStoredMessages ( messages : WorkbenchChatMessage [ ] ) : string
function sessionTabsFromConversations (
conversations : WorkbenchSessionListItem [ ]
) : WorkbenchSessionListItem [ ] ;
function sessionTabsFromMessages (
messages : WorkbenchChatMessage [ ]
) : WorkbenchSessionListItem [ ] ;
function activeSessionKeyFromRuntime (
conversationId : string | null ,
traceId : string | null
) : string
function selectSessionSidebarSession ( tab : WorkbenchSessionListItem ) : Promise < void > ;
function deleteCurrentSessionSidebarSession ( ) : Promise < void > ;
function createSessionSidebarSession ( ) : Promise < void > ;
function loadSessionSidebar ( options ? : { quiet? : boolean } ) : Promise < void > ;
function refreshSessionSidebar ( options ? : { quiet? : boolean } ) : void ;
function renderSessionSidebar ( ) : void ;
function renderSessionModelChannel ( ) : void ;
function renderCopySessionIdButton ( activeConversation : WorkbenchSessionListItem | null ) : void ;
function initCopySessionIdButton ( ) : void ;
function copyTextToClipboard ( value : string ) : Promise < boolean > ;
function sessionSidebarStatusText ( count : number ) : string ;
function sessionSidebarConversations ( ) : WorkbenchSessionListItem [ ] ;
function sessionSidebarConversationsRaw ( ) : WorkbenchSessionListItem [ ] ;
function currentStateConversationSnapshot ( ) : WorkbenchChatMessage [ ] ;
function deduplicateConversationsByThread (
conversations : WorkbenchSessionListItem [ ]
) : WorkbenchSessionListItem [ ] ;
function ensureWorkbenchWorkspace ( ) : Promise < WorkbenchUnknown > ;
function persistWorkbenchWorkspace ( payload : WorkbenchUnknown ) : Promise < WorkbenchUnknown > ;
function workspaceToStoredSessionPayload ( workspace : WorkbenchWorkspacePayload ) : WorkbenchUnknown ;
function accountConversationToStoredSessionPayload (
conversation : WorkbenchSessionListItem
) : WorkbenchUnknown ;
function showDeviceDetail ( args : { title : string ; body : HTMLElement } ) : void ;
function closeWorkbenchDialog ( dialog : HTMLDialogElement | null ) : void ;
function initSkillsPanel ( ) : void ;
function renderSkillsSurface ( ) : void ;
function initDevicePodPanel ( ) : void ;
function initLiveBuildOverlay ( ) : void ;
function initLayoutSizing ( ) : void ;
function initLeftSidebarToggle ( ) : void ;
function initRightSidebarToggle ( ) : void ;
function initSessionSidebar ( ) : void ;
function initSessionSidebarResize ( ) : void ;
function initRightSidebarResize ( ) : void ;
function setLeftSidebarCollapsed ( collapsed : boolean , options ? : { silent? : boolean } ) : void ;
function setRightSidebarCollapsed ( collapsed : boolean , options ? : { silent? : boolean } ) : void ;
function setSessionSidebarWidth ( width : number , options ? : { silent? : boolean } ) : void ;
function setRightSidebarWidth ( width : number , options ? : { silent? : boolean } ) : void ;
function markDeviceEventScrollIntent ( ) : void ;
function deviceEventUserActive ( ) : boolean ;
function setDeviceEventFollow ( follow : boolean ) : void ;
function canResizeSessionSidebar ( width : number ) : boolean ;
function canResizeRightSidebar ( width : number ) : boolean ;
function clampSessionSidebarWidth ( width : number ) : number ;
function clampRightSidebarWidth ( width : number ) : number ;
function finishSessionSidebarResize ( event : PointerEvent ) : void ;
function finishRightSidebarResize ( event : PointerEvent ) : void ;
function loadHelpSurface ( ) : Promise < void > ;
function renderHelpSurface ( ) : void ;
function initHelpSurface ( ) : void ;
function loadLiveSurface ( ) : Promise < void > ;
function renderLiveSurface ( ) : void ;
function initLiveSurface ( ) : void ;
function loadSkillsSurface ( ) : Promise < void > ;
function renderSkillPreview ( skill : WorkbenchSkillItem ) : void ;
function uploadSelectedSkillFiles ( input : HTMLInputElement ) : Promise < void > ;
function patchMessageTracePanel ( message : WorkbenchChatMessage ) : void ;
function patchTracePanelElement ( panel : HTMLElement , replacement : HTMLElement ) : void ;
function appendTraceEvent ( message : WorkbenchChatMessage , event : WorkbenchTraceEvent ) : void ;
function reconcileTraceResultFixture ( message : WorkbenchChatMessage ) : void ;
function latestAgentMessageText ( ) : string ;
function installWorkbenchTestHooks ( ) : void ;
function isLocalWorkbenchTestHost ( ) : boolean ;
function renderDevicePodSummary ( ) : void ;
function renderDevicePodInterfaces ( ) : void ;
function renderDeviceEventStream ( ) : void ;
function formatDeviceEventLine ( line : WorkbenchUnknown ) : string ;
function shortEvidenceToken ( value : string ) : string ;
function classifyWorkbenchLiveStatus ( live : WorkbenchLiveSurface | null ) : WorkbenchUnknown ;
function codeAgentAvailabilityFromLive ( live : WorkbenchLiveSurface | null ) : WorkbenchCodeAgentAvailability
function classifyCodeAgentStatusSummary ( input : {
availability : WorkbenchCodeAgentAvailability
latestMessage : WorkbenchChatResult
live : WorkbenchLiveSurface
} ) : WorkbenchUnknown ;
function codeAgentRuntimePathFromMessage ( message : WorkbenchChatMessage ) : string
function compactRunnerTraceSummary ( trace : WorkbenchRunnerTrace | null | undefined ) : WorkbenchUnknown ;
function compactSkillsSummary ( skills : WorkbenchSkillsState ) : WorkbenchUnknown ;
function compactToolCallsSummary ( events : WorkbenchTraceEvent [ ] ) : WorkbenchUnknown ;
function hardenRenderedMarkdown ( root : HTMLElement ) : void ;
function renderMessageMarkdown ( text : string ) : string ;
function messageMarkdownStatusClass ( message : WorkbenchChatMessage ) : string ;
function computeCodeAgentComposerState ( args : {
status : string ;
result : WorkbenchChatResult
sessionStatus : string
} ) : WorkbenchUnknown ;
function ensureWorkbenchAuth ( args : {
loginShell : HTMLElement
appShell : HTMLElement
} ) : Promise < WorkbenchAuthSession > ;
function initWorkbenchLogout ( button : HTMLElement | null ) : void ;
function traceAssistantSummaryRow ( message : WorkbenchChatMessage ) : WorkbenchUnknown ;
function seedCompletedAgentMessage ( payload : {
text : string ;
traceId? : string ;
status? : string ;
} ) : WorkbenchChatMessage ;
function seedTraceMessage ( payload : {
traceId : string ;
text? : string ;
status? : string ;
} ) : WorkbenchChatMessage ;
function appendTraceEvents (
traceId : string ,
events : WorkbenchTraceEvent [ ]
) : WorkbenchChatMessage
function replaceTraceAssistantStream ( args : {
traceId : string ;
text : string ;
status? : string ;
} ) : WorkbenchChatMessage
function traceScrollMetrics ( ) : WorkbenchUnknown ;
function traceDomIdentity ( ) : WorkbenchUnknown ;
function traceBodyDomIdentity ( ) : WorkbenchUnknown ;
function traceRowTexts ( ) : string [ ] ;
function setTraceBodyScrollTop ( top : number ) : void ;
function setTraceScrollTop ( top : number ) : void ;
function setConversationScrollTop ( top : number ) : void ;
function resetProgrammaticScrollWriteCount ( ) : number ;
function recordField ( name : string , value : WorkbenchUnknown ) : HTMLElement ;
const CODEX_RUNNER_CAPABLE_PROVIDERS : readonly string [ ] ;
const UNTRUSTED_CODE_AGENT_PROVIDER_PATTERN : RegExp ;
function openWorkbenchDialog ( body : HTMLElement , title? : string ) : HTMLDialogElement ;
function formatTraceDuration ( ms : number ) : string ;
function runnerTraceHeadline ( trace : WorkbenchRunnerTrace | null | undefined ) : string ;
function traceDisplayRows ( message : WorkbenchChatMessage ) : WorkbenchUnknown [ ] ;
function traceActionButton ( label : string , options ? : { className? : string } ) : HTMLButtonElement ;
function messageTraceJson ( message : WorkbenchChatMessage ) : string ;
function downloadTraceJson ( message : WorkbenchChatMessage ) : void ;
function updateCodeAgentProviderProfile ( value : string ) : void ;
function updateCodeAgentTimeout ( value : number ) : void ;
function updateGatewayShellTimeout ( value : number ) : void ;
}
export { } ;
Lyon