System primitives, permission models, and failure semantics.

The WinScript API surface is designed for agents that need typed tooling, predictable namespaces, and clear recovery behavior when Windows state does not cooperate.

Typed primitivesPermission modelRetry semantics

System primitives

Each primitive exposes a different layer of Windows control. Agents can work with one namespace while the runtime decides which surface fits the job and what recovery information needs to come back.

Primitive	Namespace	Description	Latency
App IPC	winscript.ipc.*	Low-level inter-process communication for Windows native applications.	REAL-TIME
UI Access	winscript.ui.anchor.*	Access to accessibility trees, window handles, and visual element queries.	ASYNC
Scripting	winscript.core.eval.*	Dynamic execution of automation logic with runtime isolation.	ASYNC

Security architecture

Open by default inside the automation workspace.

WinScript assumes primary visual access to any application context registered in the automation manifest. That keeps the runtime usable for real work while still bounding execution to the active user session and the surfaces the operator has chosen to expose.

Implicit trust

Standard operations do not require extra prompts once the workspace is configured.

Scope bound

Execution stays locked to the active session and the registered automation context.

Error handling

WinScriptMaxRetriesError

This exception is thrown when a system primitive cannot stabilize after the default or custom retry limit. It usually signals an unrecoverable UI state, blocked IPC channel, or missing surface.

try {
  await app.launch();
} catch (error) {
  if (error instanceof WinScriptMaxRetriesError) {
    console.error("Critical failure");
  }
}

Implementation strategy

When designing automation flows, prefer IPC or object-model access before falling back to raw UI actions. That keeps workflows faster, more stable, and less sensitive to visual changes in the desktop.

1. Request handles

Acquire persistent pointers to target windows or applications through the appropriate namespace before sending actions.

2. Prefer stable channels

Use IPC or COM whenever the application exposes them. Treat raw UI interaction as the control surface of last resort.

3. Bubble failures intentionally

Retry logic belongs in the runtime and the caller. Do not assume lower layers will silently recover on behalf of the workflow.