@knowlearning/agents 0.7.7 → 0.8.1

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))
     }
   })
 
@@ -60,44 +65,29 @@ export default function EmbeddedAgent() {
     //  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
   }
 
-  function state(scope, user, domain) {
-    let watchFn
-    let resolveKey
-    const key = new Promise(r => resolveKey = r)
+  const tagTypeToTargetCache = {}
+  async function tagIfNotYetTaggedInSession(tag_type, target) {
+    const targetCache = tagTypeToTargetCache[tag_type]
+    if (targetCache && targetCache[target]) return
 
-    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 }))
-    })
+    //  always use absolute referene when tagging
+    if (!isUUID(target)) target = (await metadata(target)).id
 
-    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
-    }
+    if (!tagTypeToTargetCache[tag_type]) tagTypeToTargetCache[tag_type] = {}
+    tagTypeToTargetCache[tag_type][target] = true
 
-    promise.unwatch = () => {
-      key
-        .then( k => {
-          watchers[k] = watchers[k].filter(x => x !== watchFn)
-          if (watchers[k].length === 0) delete watchers[k]
-        })
+    await tag(tag_type, target)
+  }
 
-      return promise
-    }
 
-    return promise
+  function watch(id, fn) {
+    tagIfNotYetTaggedInSession('subscribed', id)
+    if (!watchers[id]) watchers[id] = []
+    watchers[id].push(fn)
+    return () => removeWatcher(id, fn)
   }
 
   async function patch(root, scopes) {
@@ -105,23 +95,27 @@ 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
-
-    if (initialize) {
-      //  TODO: consider setting up watcher and updating state
-      return new MutableProxy(await state(scope) || {}, handlePatch)
+  async function state(scope) {
+    if (scope === undefined) {
+      const { context } = await environment()
+      scope = JSON.stringify(context)
     }
-    else return new MutableProxy({}, handlePatch)
+    tagIfNotYetTaggedInSession('subscribed', 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)
+    })
+
   }
 
   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 })
   }
 
@@ -181,8 +175,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) {
@@ -190,25 +203,30 @@ 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' }) }
+  function close() { return send({ type: 'close' }) }
 
   return {
+    embedded: true,
+    uuid,
     environment,
     login,
     logout,
     create,
     state,
+    watch,
     upload,
     download,
     interact,
     patch,
-    mutate,
     reset,
     metadata,
     disconnect,
-    reconnect
+    reconnect,
+    synced,
+    close,
+    tag
   }
 }

package/agents/browser/initialize.js

@@ -1,19 +1,170 @@
 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') {
+      console.log('closing?', listeners)
+      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/browser/root.js

@@ -24,9 +24,6 @@ export default () => {
     reboot: () => window.location.reload()
   })
 
-  const { state } = agent
-  //  TODO: remove agent.state proxy here as part of "get rid of default scope" work
-  agent.state = (scope=host,user,domain) => state(scope, user, domain)
   agent.local = () => {
     if (isLocal()) return
 
@@ -39,6 +36,9 @@ export default () => {
     localStorage.removeItem('api')
     location.reload()
   }
+  agent.close = () => {
+    window.close()
+  }
 
   return agent
 }

package/agents/generic.js

@@ -5,6 +5,7 @@ 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) {
@@ -13,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
@@ -22,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 = {}
@@ -31,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
@@ -41,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')
@@ -52,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) {
@@ -76,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()})
@@ -136,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)
@@ -152,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()
               }
@@ -170,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)
@@ -190,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
             }
           }
         }
@@ -212,27 +210,41 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     checkHeartbeat()
   }
 
-  function create({ id=uuid(), active_type, active }) {
+  function create({ id=uuid(), active_type, active, name }) {
     //  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 }])
+    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) => {
+  function state(scope='[]') {
+    tagIfNotYetTaggedInSession('subscribed', 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()
           create({
-            id: subscriptionId,
+            id,
             active_type: SUBSCRIPTION_TYPE,
             active: { session, scope, ii: null }
           })
@@ -240,7 +252,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
           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...
@@ -253,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) {
@@ -277,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) {
@@ -352,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})
 
@@ -409,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() {
@@ -436,6 +429,13 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     return lastMessageResponse()
   }
 
+  function tag(tag_type, target, context=[]) {
+    return create({
+      active_type: TAG_TYPE,
+      active: { tag_type, target, context }
+    })
+  }
+
   return {
     uuid,
     environment,
@@ -455,6 +455,7 @@ export default function Agent({ host, token, WebSocket, protocol='ws', uuid, fet
     synced,
     disconnect,
     reconnect,
+    tag,
     debug
   }
 }

package/browser.js

@@ -1,5 +1,6 @@
 export { default as GenericAgent } from './agents/generic.js'
 export { default as browserAgent } from './agents/browser/initialize.js'
 export { default as vuePersistentStore } from './persistence/vuex.js'
-export { default as vueContentComponent } from './vue/3/content.vue'
+export { default as vueEmbedComponent } from './vue/3/content.vue'
+export { default as vueNameComponent } from './vue/3/name.vue'
 export { default as vuePersistentComponent } from './vue/3/component.js'

package/package.json

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

package/vue/3/content.vue

@@ -26,6 +26,7 @@ export default {
       this.embedding = Agent.embed({ id }, iframe)
       this.embedding.on('state', e => this.$emit('state', e))
       this.embedding.on('mutate', e => this.$emit('mutate', e))
+      this.embedding.on('close', e => this.$emit('close', e))
 
 /*
       const { handle } = this.embedding

package/vue/3/name.vue

@@ -0,0 +1,45 @@
+<template>
+  <span
+    draggable="true"
+    @dragstart="handleDragStart"
+  >
+    {{ loading ? '...' : name }}
+  </span>
+</template>
+
+<script>
+  export default {
+    props: {
+      id: String
+    },
+    data() {
+      return {
+        loading: true,
+        metadata: null
+      }
+    },
+    async created() {
+      this.metadata = await Agent.metadata(this.id)
+      this.loading = false
+    },
+    computed: {
+      name() {
+        if (this.loading) return
+        else return this.metadata && this.metadata.name ? this.metadata.name : 'unnamed'
+      }
+    },
+    methods: {
+      handleDragStart(e) {
+        e.dataTransfer.effectAllowed = 'move';
+        e.dataTransfer.setData('text/plain', this.id);
+      }
+    }
+  }
+</script>
+
+<style>
+  span
+  {
+    cursor: grab;
+  }
+</style>

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
-  }
-}