#Main script sessions

ScriptSession is global or imported from "scripting". It targets one explicitly registered, already-running index/home_screen session of the same script in the same App process. This supports the main-app App Intent reuse path. It does not send across genuine extension processes, wake the App or start another script; missing receivers fail explicitly.

// index.tsx: keep your normal main UI/session alive.
import { ScriptSession, Storage } from "scripting"
const id = ScriptSession.register(async message => {
  // Validate your application command and perform the operation here.
  // Return acknowledgement before exiting/unregistering this main script.
  return { accepted: true, message }
})
Storage.set("mainSessionID", id)
// On normal shutdown: ScriptSession.unregister(id)

// app_intents.tsx
import { AppIntentManager, AppIntentProtocol, ScriptSession, Storage } from "scripting"
export const StopMainIntent = AppIntentManager.register({
  name: "StopMainIntent",
  protocol: AppIntentProtocol.LiveActivityIntent,
  perform: async () => {
    const id = Storage.get<string>("mainSessionID")
    if (!id) throw new Error("Start the main script first")
    console.log(await ScriptSession.request(id, { command: "stop" }, { timeout: 5000 }))
  },
})

IDs are fresh per registration; stale IDs never target replacement sessions. One receiver per script; at most 32 sessions and 32 pending requests per process. Input/reply are JSON-compatible, up to 64 KiB each. Handler undefined means a null reply. Functions, symbols, BigInt, nonfinite numbers, undefined fields and cyclic data are rejected.

Reply timeout defaults to 10000 ms, configurable 100...30000. Expired queued commands are not delivered after resume. Timeout does not undo accepted work, preempt synchronous JS or prove the main session died. A stop acknowledgement does not prove physical location restoration. Exit/unregister rejects pending requests and releases handlers; late replies are ignored. Return your reply before Script.exit.

Error codes: SCRIPT_SESSION_UNAVAILABLE, SCRIPT_SESSION_NOT_FOUND, SCRIPT_SESSION_BUSY, SCRIPT_SESSION_CLOSED, SCRIPT_SESSION_TIMEOUT, SCRIPT_SESSION_INVALID_DATA, SCRIPT_SESSION_INVALID_HANDLER, SCRIPT_SESSION_HANDLER_FAILED, ERR_PRO_REQUIRED.