Sessions

// Agent starts a session
POST /surf/session/start
// => { "ok": true, "sessionId": "sess_abc123" }
 
// Execute commands with session context
POST /surf/execute
{
  "command": "cart.add",
  "params": { "sku": "LAPTOP-01" },
  "sessionId": "sess_abc123"
}
 
// The handler receives session state in ctx.state
const surf = await createSurf({
  name: 'My Store',
  commands: {
    'cart.add': {
      description: 'Add item to cart',
      params: { sku: { type: 'string', required: true } },
      run: async ({ sku }, ctx) => {
        const cart = (ctx.state?.cart as string[]) ?? []
        cart.push(sku)
        // Return state to persist it
        return { cart, added: sku }
      },
    },
    'cart.view': {
      description: 'View cart',
      run: async (_, ctx) => {
        return { items: ctx.state?.cart ?? [] }
      },
    },
  },
})
 
// End session when done
POST /surf/session/end
{ "sessionId": "sess_abc123" }