@knowlearning/agents 0.7.6 → 0.8.0

package/agents/browser/embedded.js

@@ -1,4 +1,4 @@
-import { v1 as uuid } from 'uuid'
+import { validate as isUUID, v1 as uuid } from 'uuid'
 import MutableProxy from '../../persistence/json.js'
 
 export default function EmbeddedAgent() {
@@ -8,6 +8,12 @@ export default function EmbeddedAgent() {
   const responses = {}
   const watchers = {}
 
+  function removeWatcher(key, fn) {
+    const watcherIndex = watchers[key].findIndex(x => x === fn)
+    if (watcherIndex > -1) watchers[key].splice(watcherIndex, 1)
+    else console.warn('TRIED TO REMOVE WATCHER THAT DOES NOT EXIST')
+  }
+
   async function send(message) {
     const requestId = message.requestId || uuid()
 
@@ -46,9 +52,8 @@ export default function EmbeddedAgent() {
       else resolve(data.response)
     }
     else if (data.ii !== undefined) {
-      const { domain, user, scope } = data
-      const key = `${domain}/${user}/${scope}`
-      if (watchers[key]) watchers[key].forEach(fn => fn(data))
+      const { scope } = data
+      if (watchers[scope]) watchers[scope].forEach(fn => fn(data))
     }
   })
 
@@ -56,42 +61,33 @@ export default function EmbeddedAgent() {
     return send({ type: 'environment' })
   }
 
-  function state(scope, user, domain) {
-    let watchFn
-    let resolveKey
-    const key = new Promise(r => resolveKey = r)
+  function create({ id=uuid(), active_type, active }) {
+    //  TODO: collapse into 1 patch and 1 interact call
+    interact(id, [{ op: 'add', path: ['active_type'], value: active_type }])
+    interact(id, [{ op: 'add', path: ['active'], value: active }])
+    return id
+  }
 
-    const promise = new Promise(async resolve => {
-      const { domain: d, auth: { user: u }, scope: s } = await environment()
-      domain = domain || d
-      user = user || u
-      scope = scope || s
-      resolveKey(`${domain}/${user}/${scope}`)
-      resolve(send({ type: 'state', scope, user, domain }))
-    })
+  const tagTypeToTargetCache = {}
+  async function tagIfNotYetTaggedInSession(tag_type, target) {
+    const targetCache = tagTypeToTargetCache[tag_type]
+    if (targetCache && targetCache[target]) return
 
-    promise.watch = fn => {
-      key
-        .then( async k => {
-          if (watchFn) throw new Error('Only one watcher allowed')
-          if (!watchers[k]) watchers[k] = []
-          watchers[k].push(fn)
-          watchFn = fn
-        })
-      return promise
-    }
+    //  always use absolute referene when tagging
+    if (!isUUID(target)) target = (await metadata(target)).id
 
-    promise.unwatch = () => {
-      key
-        .then( k => {
-          watchers[k] = watchers[k].filter(x => x !== watchFn)
-          if (watchers[k].length === 0) delete watchers[k]
-        })
+    if (!tagTypeToTargetCache[tag_type]) tagTypeToTargetCache[tag_type] = {}
+    tagTypeToTargetCache[tag_type][target] = true
 
-      return promise
-    }
+    await tag(tag_type, target)
+  }
 
-    return promise
+
+  function watch(id, fn) {
+    tagIfNotYetTaggedInSession('connected', id)
+    if (!watchers[id]) watchers[id] = []
+    watchers[id].push(fn)
+    return () => removeWatcher(id, fn)
   }
 
   async function patch(root, scopes) {
@@ -99,23 +95,23 @@ export default function EmbeddedAgent() {
     return send({ type: 'patch', root, scopes })
   }
 
-  async function mutate (scope, initialize=true) {
-    const handlePatch = patch => interact(scope, patch)
-
-    if (!scope) scope = (await environment()).scope
+  async function state(scope) {
+    tagIfNotYetTaggedInSession('connected', scope)
+    const startState = await send({ type: 'state', scope })
+    return new MutableProxy(startState, patch => {
+      const activePatch = structuredClone(patch)
+      activePatch.forEach(entry => entry.path.unshift('active'))
+      interact(scope, activePatch)
+    })
 
-    if (initialize) {
-      //  TODO: consider setting up watcher and updating state
-      return new MutableProxy(await state(scope) || {}, handlePatch)
-    }
-    else return new MutableProxy({}, handlePatch)
   }
 
   function reset(scope) {
-    return interact(scope, [{ op: 'add', path:[], value: null }])
+    return interact(scope, [{ op: 'add', path:['active'], value: null }])
   }
 
   function interact(scope, patch) {
+    tagIfNotYetTaggedInSession('mutated', scope)
     return send({ type: 'interact', scope, patch })
   }
 
@@ -175,8 +171,27 @@ export default function EmbeddedAgent() {
     return promise
   }
 
-  function metadata(id) {
-    return state(id, 'metadata', 'core')
+  function isValidMetadataMutation({ path, op, value }) {
+    return (
+      ['active_type', 'name'].includes(path[0])
+      && path.length === 1
+      && typeof value === 'string' || op === 'remove'
+    )
+  }
+
+  async function metadata(scope) {
+    const md = await send({ type: 'metadata', scope })
+    return new MutableProxy(md, patch => {
+      const activePatch = structuredClone(patch)
+      activePatch.forEach(entry => {
+        if (!isValidMetadataMutation(entry)) throw new Error('You may only modify the type or name for a scope\'s metadata')
+      })
+      interact(scope, activePatch)
+    })
+  }
+
+  function tag(tag_type, target, context=[]) {
+    return send({ type: 'tag', tag_type, target, context })
   }
 
   function login(provider, username, password) {
@@ -184,24 +199,28 @@ export default function EmbeddedAgent() {
   }
 
   function logout() { return send({ type: 'logout' }) }
-
   function disconnect() { return send({ type: 'disconnect' }) }
-
   function reconnect() { return send({ type: 'reconnect' }) }
+  function synced() { return send({ type: 'synced' }) }
 
   return {
+    embedded: true,
+    uuid,
     environment,
     login,
     logout,
+    create,
     state,
+    watch,
     upload,
     download,
     interact,
     patch,
-    mutate,
     reset,
     metadata,
     disconnect,
-    reconnect
+    reconnect,
+    synced,
+    tag
   }
 }

package/agents/browser/initialize.js

@@ -1,19 +1,169 @@
 import RootAgent from './root.js'
 import EmbeddedAgent from './embedded.js'
-import embed from './embed.js'
+import { v1 as uuid, validate as validateUUID } from 'uuid'
 
-let agentInstance
+let Agent
 
-export default function() {
-  if (agentInstance) return agentInstance
+export default function browserAgent() {
+  if (Agent) return Agent
 
   let embedded
 
   try { embedded = window.self !== window.top }
   catch (e) { embedded = true }
 
-  agentInstance = embedded ? EmbeddedAgent() : RootAgent()
-  agentInstance.embed = embed
+  Agent = embedded ? EmbeddedAgent() : RootAgent()
+  Agent.embed = embed
 
-  return agentInstance
+  return Agent
+}
+
+const copy = x => JSON.parse(JSON.stringify(x))
+
+const watchers = {}
+
+function embed(environment, iframe) {
+  const postMessageQueue = []
+  const listeners = {}
+  let frameLoaded = false
+  let embeddedAgentInitialized = false
+
+  const session = uuid()
+
+  const postMessage = m => new Promise((resolve, reject) => {
+    const message = { ...copy(m), session }
+    postMessageQueue.push({ message, sent: resolve })
+    if (frameLoaded) processPostMessageQueue()
+  })
+
+  const processPostMessageQueue = () => {
+    while (iframe.parentNode && postMessageQueue.length) {
+      const { message, sent } = postMessageQueue.shift()
+      iframe.contentWindow.postMessage(message, '*')
+      sent()
+    }
+  }
+
+  const handleMessage = async message => {
+    const { requestId, type } = message
+
+    const sendDown = response => postMessage({ requestId, response })
+
+    if (type === 'error') {
+      console.error(message)
+      sendDown({})
+    }
+    else if (type === 'close') {
+      if (listeners.close) listeners.close()
+    }
+    else if (type === 'environment') {
+      const env = await Agent.environment()
+      const context = [...env.context, environment.id]
+      Object.assign(env, { ...env, context })
+      sendDown(env)
+    }
+    else if (type === 'interact') {
+      const { scope, patch } = message
+      await Agent.interact(scope, patch)
+      if (listeners.mutate) listeners.mutate({ scope })
+      sendDown({}) // TODO: might want to send down the interaction index
+    }
+    else if (type === 'metadata') {
+      sendDown(await Agent.metadata(message.scope))
+    }
+    else if (type === 'tag') {
+      const { tag_type, target, context } = message
+      const prependedContext = [environment.id, ...context]
+      sendDown(await Agent.tag(tag_type, target, prependedContext))
+    }
+    else if (type === 'state') {
+      const { scope } = message
+
+      const statePromise = Agent.state(scope)
+
+      if (!watchers[scope]) watchers[scope] = Agent.watch(scope, postMessage)
+
+      if (listeners.state) listeners.state({ scope })
+      sendDown(await statePromise)
+    }
+    else if (type === 'patch') {
+      const { root, scopes } = message
+      sendDown(await Agent.patch(root, scopes))
+    }
+    else if (type === 'upload') {
+      const { name, contentType, id } = message
+      sendDown(await Agent.upload(name, contentType, undefined, id))
+    }
+    else if (type === 'download') {
+      sendDown(await Agent.download(message.id).url())
+    }
+    else if (type === 'login') {
+      const { provider, username, password } = message
+      sendDown(await Agent.login(provider, username, password))
+    }
+    else if (type === 'logout') Agent.logout()
+    else if (type === 'disconnect') sendDown(await Agent.disconnect())
+    else if (type === 'reconnect') sendDown(await Agent.reconnect())
+    else if (type === 'synced') sendDown(await Agent.synced())
+    else {
+      console.log('Unknown message type passed up...', message)
+      sendDown({})
+    }
+  }
+
+  window.addEventListener('message', ({ data }) => {
+    if (data.session === session) {
+      embeddedAgentInitialized = true
+      //  TODO: ensure message index ordering!!!!!!!!!!!!!!!!!!!! (no order guarantee given in postMessage protocol, so we need to make a little buffer here)
+      handleMessage(data)
+    }
+  })
+
+  //  write in a temporary loading notification while frame loads
+  const cw = iframe.contentWindow
+  if (cw) cw.document.body.innerHTML = 'Loading...'
+
+  //  TODO: make sure content security policy headers for embedded domain always restrict iframe
+  //        src to only self for embedded domain
+  iframe.onload = () => {
+    frameLoaded = true
+    processPostMessageQueue()
+  }
+
+  setUpEmbeddedFrame()
+
+  async function setUpEmbeddedFrame() {
+    browserAgent()
+
+    const { protocol } = window.location
+    const { id } = environment
+    if (validateUUID(id)) {
+      const { domain } = await Agent.metadata(id)
+      iframe.src = `${protocol}//${domain}/${id}`
+    }
+    else iframe.src = id //  TODO: ensure is url
+
+    while(!embeddedAgentInitialized) {
+      postMessage({ type: 'setup', session })
+      await new Promise(r => setTimeout(r, 100))
+    }
+  }
+
+  function remove () {
+    if (iframe.parentNode) iframe.parentNode.removeChild(iframe)
+  }
+
+  function on(event, fn) {
+    listeners[event] = fn
+  }
+
+  function auth(token, state) {
+    postMessage({ type: 'auth', token, state })
+  }
+
+  return {
+    auth,
+    remove,
+    on
+  }
 }

package/agents/download.js

@@ -1,11 +1,11 @@
-export default function download (id, { uuid, initialize, lastMessageResponse, fetch, metadata }) {
+const DOWNLOAD_TYPE = 'application/json;type=download'
+
+export default function download (id, { create, lastMessageResponse, fetch, metadata }) {
   // TODO: initialize size info
-  const downloadId = uuid()
-  initialize(
-    downloadId,
-    'application/json;type=download',
-    { id }
-  )
+  create({
+    active_type: DOWNLOAD_TYPE,
+    active: { id }
+  })
 
   let mode = 'fetch'
 
@@ -25,7 +25,7 @@ export default function download (id, { uuid, initialize, lastMessageResponse, f
       //  TODO: throw meaningful error if not in browser context
       //        (following block assumes browser context)
       //  TODO: use browser progress UX instead of downloading all into memory first
-      const res = await download(id, { uuid, initialize, lastMessageResponse, fetch, metadata })
+      const res = await download(id, { create, lastMessageResponse, fetch, metadata })
       const { name } = await metadata(id)
       const type = res.headers.get('Content-Type')
       const blob = new Blob([ await res.blob() ], { type }) 

package/agents/generic.js

@@ -2,6 +2,10 @@ import MutableProxy from '../persistence/json.js'
 import download from './download.js'
 
 const HEARTBEAT_TIMEOUT = 10000
+const UPLOAD_TYPE = 'application/json;type=upload'
+const SUBSCRIPTION_TYPE = 'application/json;type=subscription'
+const POSTGRES_QUERY_TYPE = 'application/json;type=postgres-query'
+const TAG_TYPE = 'application/json;type=tag'
 
 //  transform our custom path implementation to the standard JSONPatch path
 function standardJSONPatch(patch) {
@@ -10,6 +14,10 @@ function standardJSONPatch(patch) {
   })
 }
 
+function isUUID(string) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(string)
+}
+
 function sanitizeJSONPatchPathSegment(s) {
   if (typeof s === "string") return s.replaceAll('~', '~0').replaceAll('/', '~1')
   else return s
@@ -19,8 +27,9 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   let ws
   let user
   let domain
-  const session = uuid()
+  let session
   let server
+  let isSynced = false
   let si = -1
   let authed = false
   const states = {}
@@ -28,6 +37,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   const watchers = {}
   const keyToSubscriptionId = {}
   const lastInteractionResponse = {}
+  const tagTypeToTargetCache = {}
   const messageQueue = []
   let resolveEnvironment
   let disconnected = false
@@ -38,7 +48,6 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   let lastHeartbeat
   const syncedPromiseResolutions = []
 
-  const subscriptions = {}
   const patches = state('patches')
 
   log('INITIALIZING AGENT CONNECTION')
@@ -49,9 +58,8 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   }
 
   function resolveSyncPromises() {
-    while (syncedPromiseResolutions.length) {
-      syncedPromiseResolutions.shift()()
-    }
+    while (syncedPromiseResolutions.length) syncedPromiseResolutions.shift()()
+    isSynced = true
   }
 
   function removeWatcher(key, fn) {
@@ -73,6 +81,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   }
 
   function queueMessage(message) {
+    isSynced = false
     si += 1
     const promise = new Promise((resolve, reject) => responses[si] = [[resolve, reject]])
     messageQueue.push({...message, si, ts: Date.now()})
@@ -133,6 +142,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
           authed = true
           if (!user) { // this is the first authed websocket connection
             user = message.auth.user
+            session = message.session
             domain = message.domain
             server = message.server
             resolveEnvironment(message)
@@ -149,14 +159,13 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
         else {
           if (message.si !== undefined) {
             if (responses[message.si]) {
-              //  TODO: remove "acknowledged" messages fromt queue and do accounting with si
+              //  TODO: remove "acknowledged" messages from queue and do accounting with si
               responses[message.si]
                 .forEach(([resolve, reject]) => {
                   message.error ? reject(message) : resolve(message)
                 })
               delete responses[message.si]
               ws.send(JSON.stringify({ack: message.si})) //  acknowledgement that we have received the response for this message
-
               if (Object.keys(responses).length === 0) {
                 resolveSyncPromises()
               }
@@ -167,14 +176,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
             }
           }
           else {
-            const sub = subscriptions[keyToSubscriptionId[message.scope]]
             if (watchers[message.scope]) {
-              // TODO: debug case where sub is not defined
-              if (sub && sub.ii + 1 !== message.ii) {
-                //  TODO: this seems to be an error that happens with decent regularity (an answer with a given si was skipped/failed)
-                //        we should be wary of out-of-order ii being passed down (maybe need to wait for older ones???)
-                console.warn('UNEXPECTED UPDATE INTERACTION INDEX!!!!!!!!!!! last index in session', sub, ' passed index ', message.ii)
-              }
               states[message.scope] = await states[message.scope]
 
               const lastResetPatchIndex = message.patch.findLastIndex(p => p.path.length === 0)
@@ -187,7 +189,6 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
                   const state = structuredClone(states[message.scope].active)
                   fn({ ...message, state })
                 })
-              if (sub) sub.ii = message.ii
             }
           }
         }
@@ -209,43 +210,49 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     checkHeartbeat()
   }
 
-  function initialize(id, type, value) {
+  function create({ id=uuid(), active_type, active }) {
     //  TODO: collapse into 1 patch and 1 interact call
-    interact(id, [{
-      op: 'add',
-      path: ['active_type'],
-      value: type
-    }])
-    interact(id, [{
-      op: 'add',
-      path: ['active'],
-      value
-    }])
+    interact(id, [{ op: 'add', path: ['active_type'], value: active_type }], false)
+    interact(id, [{ op: 'add', path: ['active'], value: active }], false)
+    return id
+  }
+
+  async function tagIfNotYetTaggedInSession(tag_type, target) {
+    const targetCache = tagTypeToTargetCache[tag_type]
+    if (targetCache && targetCache[target]) return
+
+    if (!targetCache) tagTypeToTargetCache[tag_type] = {}
+    tagTypeToTargetCache[tag_type][target] = true
+
+      //  always use absolute referene when tagging
+    if (!isUUID(target)) target = (await metadata(target)).id
+
+    await tag(tag_type, target)
   }
 
-  function environment() { return environmentPromise }
+  async function environment() {
+    return { ...(await environmentPromise), context: [] }
+  }
 
   function state(scope) {
-    let watchFn
-    const promise = new Promise(async (resolveState, rejectState) => {
+    tagIfNotYetTaggedInSession('connected', scope)
+    return new Promise(async (resolveState, rejectState) => {
       if (!keyToSubscriptionId[scope]) {
         const id = uuid()
 
         keyToSubscriptionId[scope] = id
         watchers[scope] = []
         states[scope] = new Promise(async (resolve, reject) => {
-
-          const subscriptionId = uuid()
-          initialize(
-            subscriptionId,
-            'application/json;type=subscription',
-            { session, scope, ii: null }
-          )
+          create({
+            id,
+            active_type: SUBSCRIPTION_TYPE,
+            active: { session, scope, ii: null }
+          })
 
           try {
             const state = await lastMessageResponse()
             //  TODO: replace with editing scope of type
-            interact(subscriptionId, [{
+            interact(id, [{
               op: 'add',
               path: ['active', 'ii'],
               value: 1 // TODO: use state.ii when is coming down properly...
@@ -258,7 +265,6 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
               // ii does not apply (we clear out the subscription to not cache value)
               delete states[scope]
               delete keyToSubscriptionId[scope]
-              delete subscriptions[id]
             }
           }
           catch (error) {
@@ -282,26 +288,6 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
         rejectState(error)
       }
     })
-
-    promise.watch = fn => {
-      if (watchFn) throw new Error('Only one watcher allowed')
-      if (!watchers[scope]) watchers[scope] = []
-      watchers[scope].push(fn)
-      watchFn = fn
-
-      return promise
-    }
-
-    promise.unwatch = async () => {
-      removeWatcher(scope, watchFn)
-      if (watchers[scope].length === 0) {
-        delete subscriptions[keyToSubscriptionId[scope]]
-        delete keyToSubscriptionId[scope]
-        delete watchers[scope]
-      }
-    }
-
-    return promise
   }
 
   function watch(id, fn) {
@@ -334,15 +320,10 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   //  TODO: if no data, set up streaming upload
   async function upload(name, type, data, id=uuid()) {
     //  TODO: include data size info...
-    const uploadId = uuid()
-    initialize(
-      uploadId,
-      'application/json;type=upload',
-      {
-        id,
-        type
-      }
-    )
+    create({
+      active_type: UPLOAD_TYPE,
+      active: { id, type }
+    })
     const { url } = await lastMessageResponse()
 
     if (data === undefined) return url
@@ -362,7 +343,9 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     return { swaps }
   }
 
-  async function interact(scope, patch) {
+  //  TODO: addTag option should probably not be exposed
+  async function interact(scope, patch, addTag=true) {
+    if (addTag) tagIfNotYetTaggedInSession('mutated', scope)
     //  TODO: ensure user is owner of scope
     const response = queueMessage({scope, patch})
 
@@ -419,7 +402,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   }
 
   async function synced() {
-    return new Promise(resolve => syncedPromiseResolutions.push(resolve))
+    return isSynced ? null : new Promise(resolve => syncedPromiseResolutions.push(resolve))
   }
 
   function disconnect() {
@@ -439,23 +422,30 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
   }
 
   function query(query, params, domain) {
-    initialize(
-      uuid(),
-      'application/json;type=postgres-query',
-      { query, params, domain }
-    )
+    create({
+      active_type: POSTGRES_QUERY_TYPE,
+      active: { query, params, domain }
+    })
     return lastMessageResponse()
   }
 
+  function tag(tag_type, target, context=[]) {
+    return create({
+      active_type: TAG_TYPE,
+      active: { tag_type, target, context }
+    })
+  }
+
   return {
     uuid,
     environment,
     login,
     logout,
+    create,
     state,
     watch,
     upload,
-    download: id => download(id, { uuid, initialize, lastMessageResponse, fetch, download, metadata }),
+    download: id => download(id, { create, lastMessageResponse, fetch, metadata }),
     interact,
     patch,
     claim,
@@ -465,6 +455,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     synced,
     disconnect,
     reconnect,
+    tag,
     debug
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowlearning/agents",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "API for embedding applications in KnowLearning systems.",
   "main": "node.js",
   "browser": "browser.js",

package/vue/3/component.js

@@ -1,4 +1,7 @@
 import { watchEffect, defineAsyncComponent } from 'vue'
+import { browserAgent } from '../../browser.js'
+
+const Agent = browserAgent()
 
 //  TODO: probably want to make this a util, and better fleshed out (with white instead of blacklist)
 function isScopeSerializable(v) {

package/agents/browser/embed.js

@@ -1,146 +0,0 @@
-import { v1 as uuid, validate as validateUUID } from 'uuid'
-
-const copy = x => JSON.parse(JSON.stringify(x))
-
-const watchers = {}
-
-export default function embed(environment, iframe) {
-  const postMessageQueue = []
-  const listeners = {}
-  let frameLoaded = false
-  let embeddedAgentInitialized = false
-
-  const session = uuid()
-
-  const postMessage = m => new Promise((resolve, reject) => {
-    const message = { ...copy(m), session }
-    postMessageQueue.push({ message, sent: resolve })
-    if (frameLoaded) processPostMessageQueue()
-  })
-
-  const processPostMessageQueue = () => {
-    while (iframe.parentNode && postMessageQueue.length) {
-      const { message, sent } = postMessageQueue.shift()
-      iframe.contentWindow.postMessage(message, '*')
-      sent()
-    }
-  }
-
-  const handleMessage = async message => {
-    const { requestId, type } = message
-
-    const sendDown = response => {
-      if (message.type === 'environment') Object.assign(response, environment)
-      return postMessage({ requestId, response })
-    }
-
-    if (type === 'error') {
-      console.error(message)
-      sendDown({})
-    }
-    else if (type === 'close') {
-      if (listeners.close) listeners.close()
-    }
-    else if (type === 'environment') {
-      sendDown(await Agent.environment())
-    }
-    else if (type === 'interact') {
-      const { scope, patch } = message
-      await Agent.interact(scope, patch)
-      if (listeners.mutate) listeners.mutate({ scope })
-      sendDown({}) // TODO: might want to send down the interaction index
-    }
-    else if (type === 'state') {
-      const { scope, user, domain } = message
-
-      const statePromise = Agent.state(scope, user, domain)
-
-      const key = `${session}/${domain}/${user}/${scope}`
-
-      //  only watch once per key per experience session
-      if (!watchers[key]) {
-        watchers[key] = statePromise.unwatch //  TODO: consider how to use this...
-        statePromise.watch(postMessage)
-      }
-
-      if (listeners.state) listeners.state({ scope, user, domain })
-      sendDown(await statePromise)
-    }
-    else if (type === 'patch') {
-      const { root, scopes } = message
-      sendDown(await Agent.patch(root, scopes))
-    }
-    else if (type === 'upload') {
-      const { name, contentType, id } = message
-      sendDown(await Agent.upload(name, contentType, false, id))
-    }
-    else if (type === 'download') {
-      sendDown(await Agent.download(message.id).url())
-    }
-    else if (type === 'login') {
-      const { provider, username, password } = message
-      sendDown(await Agent.login(provider, username, password))
-    }
-    else if (type === 'logout') Agent.logout()
-    else if (type === 'disconnect') sendDown(await Agent.disconnect())
-    else if (type === 'reconnect') sendDown(await Agent.reconnect())
-    else {
-      console.log('Unknown message type passed up...', message)
-      sendDown({})
-    }
-  }
-
-  window.addEventListener('message', ({ data }) => {
-    if (data.session === session) {
-      embeddedAgentInitialized = true
-      //  TODO: ensure message index ordering!!!!!!!!!!!!!!!!!!!! (no order guarantee given in postMessage protocol, so we need to make a little buffer here)
-      handleMessage(data)
-    }
-  })
-
-  //  write in a temporary loading notification while frame loads
-  const cw = iframe.contentWindow
-  if (cw) cw.document.body.innerHTML = 'Loading...'
-
-  //  TODO: make sure content security policy headers for embedded domain always restrict iframe
-  //        src to only self for embedded domain
-  iframe.onload = () => {
-    frameLoaded = true
-    processPostMessageQueue()
-  }
-
-  setUpEmbeddedFrame()
-
-  async function setUpEmbeddedFrame() {
-    const { protocol } = window.location
-    const { id } = environment
-    if (validateUUID(id)) {
-      const { domain } = await Agent.metadata(id)
-      iframe.src = `${protocol}//${domain}/${id}`
-    }
-    else iframe.src = id //  TODO: ensure is url
-
-    while(!embeddedAgentInitialized) {
-      postMessage({ type: 'setup', session })
-      await new Promise(r => setTimeout(r, 100))
-    }
-  }
-
-  function remove () {
-    if (iframe.parentNode) iframe.parentNode.removeChild(iframe)
-  }
-
-  function on(event, fn) {
-    listeners[event] = fn
-  }
-
-  function auth(token, state) {
-    postMessage({ type: 'auth', token, state })
-  }
-
-  return {
-    auth,
-    remove,
-    on
-  }
-}