Arcane events

Arcane.events delivers renderer-visible host and Core events. A named subscription such as Arcane.events.on('operation.progress', listener) receives that event's payload object directly. A wildcard subscription made with Arcane.events.on('*', listener) receives an envelope shaped as { event, data }; * is a subscription selector, not an emitted event name.

Arcane.events.on() and Arcane.events.once() observe only future deliveries. Arcane.events.once() removes its subscription before invoking the listener and therefore observes only the next matching delivery. Most events are live notifications and are not replayed, so subscribe before starting the work that can emit them.

transport.ready and core.ready are the two durable completion events. Arcane.events.when(name, listener) accepts only those names. It waits once when completion has not happened, or asynchronously replays the first deeply frozen JSON snapshot when completion has already happened. Arcane.events.completed(name) reports whether a designated durable event has completed; it is not a payload accessor.

Every subscription method returns an unsubscribe function. Call it when the owning view or task is torn down. An exception thrown by one listener is caught and reported to the console, and does not stop the remaining named or wildcard listeners.

Event inventory

Subscribe and clean up

Keep the returned function with the UI or operation that owns the subscription:

const stopProgress = Arcane.events.on('operation.progress', function handleOperationProgress(data) {
  console.info(`${data.operationId}: ${data.progress}%`, data.message);
});

window.addEventListener('pagehide', stopProgress, { once: true });

A wildcard listener is useful for routing or diagnostics, but its callback shape differs from a named listener. Avoid logging payloads indiscriminately because results can contain credentials or other sensitive values.

const observedEventNames = [];
const stopObserving = Arcane.events.on('*', function handleAnyArcaneEvent({ event, data }) {
  observedEventNames.push(event);
  routeArcaneEvent(event, data);
});

window.addEventListener('pagehide', stopObserving, { once: true });

Wait for durable readiness

Use when() when a component can mount before or after readiness. The callback is still asynchronous when the durable completion already exists.

const stopReady = Arcane.events.when('core.ready', function handleCoreReady({ version, platform }) {
  showRuntimeReady({ version, platform });
});

if (Arcane.events.completed('core.ready')) {
  showRuntimeConnecting(false);
}

window.addEventListener('pagehide', stopReady, { once: true });

Do not use when() for operation, streaming, terminal, appearance, or error events. Those events have no retained completion value.

Follow a terminal lifecycle

Subscribe before Arcane.terminal.start(). Output, exit, or error delivery can race the start response, so buffer by sessionId until the returned session identifies the stream to keep. Append data chunks as delivered rather than assuming one event equals one line.

const terminalOutput = document.querySelector('[data-terminal-output]');
const buffered = [];
const maxBufferedEvents = 128;
let sessionId = null;

function handleTerminalEvent(event, data) {
  if (sessionId === null) {
    buffered.push({ event, data });
    // Bound pre-identification buffering; surface truncation in a real UI.
    if (buffered.length > maxBufferedEvents) buffered.shift();
    return;
  }
  if (data.sessionId !== sessionId) return;
  if (event === 'terminal.output') {
    terminalOutput?.append(document.createTextNode(data.data));
  } else if (event === 'terminal.exit') {
    terminalOutput?.append(document.createTextNode(`\n[exit ${data.exitCode}]`));
  } else {
    terminalOutput?.append(document.createTextNode(`\n[terminal error: ${data.message}]`));
  }
}

const stopTerminalEvents = [
  Arcane.events.on('terminal.output', function handleTerminalOutput(data) {
    handleTerminalEvent('terminal.output', data);
  }),
  Arcane.events.on('terminal.exit', function handleTerminalExit(data) {
    handleTerminalEvent('terminal.exit', data);
  }),
  Arcane.events.on('terminal.error', function handleTerminalError(data) {
    handleTerminalEvent('terminal.error', data);
  }),
];

try {
  const session = await Arcane.terminal.start({ shell: 'auto' });
  sessionId = session.id;
  for (const item of buffered.splice(0)) handleTerminalEvent(item.event, item.data);
  const lineEnding = ['powershell', 'cmd'].includes(session.shell) ? '\r\n' : '\n';
  await Arcane.terminal.write(sessionId, `echo ready${lineEnding}`);
} finally {
  if (sessionId !== null) {
    await Arcane.terminal.close(sessionId).catch(function ignoreTerminalCloseFailure() {});
  }
  for (const stop of stopTerminalEvents) stop();
}

Use the host-appropriate line ending when submitting interactive commands: \r\n for PowerShell or Command Prompt and \n for POSIX shells.

Event lifecycle guidance

• Subscribe before starting work, then correlate with requestId, operationId, streamId, or sessionId. Unrelated work can emit the same named event concurrently.
• Treat operation.completed and operation.failed as the terminal event for an operationId; progress and log events are intermediate and are not retained.
• Treat operation.completed.credentials as sensitive. Do not write it to logs or durable application storage.
• Treat streaming and terminal payloads as ordered deliveries for their correlation ID, not as complete messages or lines. Apply resource bounds when buffering.
• Unsubscribe on teardown even after a one-shot workflow. once() and a pending when() clean themselves up when invoked, but their returned unsubscribe function cancels an abandoned wait.
• Host scope describes where an event can be emitted; it does not grant the capability needed to start the underlying operation.