.env

OPENAI_API_KEY=sk-shhh
XAI_KEY=xai-shhh

0-README.md

To run:

$ vim .env # enter at least an xAI API key since that's the default provider used
$ node --env-file=.env 1-puzzle.js
```

1-puzzle.js

import complete from './2-complete.js';

globalThis.logState = false;
globalThis.logResponses = false;
globalThis.logLogs = true;

async function looptools(init) {
  while (true) {
    if (logState) { console.log(st); console.log() }
    let res = await complete(init.logs, { ...init, logs: undefined });
    logResponses && console.log(res);
    let tools = [...Object.entries(res.tools || {})];
    if (tools.length && tools[0][1].result)  init = tools[0][1].result;
    if (init === 'end') break;
    await new Promise(pres => setTimeout(pres, 1000));
  }
}

let model = 'xai:grok-4';

let st = {
  inventory: [],
  investigated: [],
  door: { oiled: false, open: false },
  lstatue: { dir: 'left', lever: false },
  rstatue: { dir: 'right', lever: false },
  debris: { picked: false },
};

let logs = [{ role: 'system', content: `Always comment on your actions, but be very very terse. When you say you're going to call a tool, don't forget to actually call it.` }, { role: 'user', content: `This is a puzzle, call the right functions to solve it. You're in a loop, so asking questions won't help. If you don't know what to do, simply try one of the available  functions, and don't repeat the same calls over and over. Hint: Facing the statues towards each other could reveal secrets.` }];

let cpurple = '\x1b[38;2;168;85;247m';
let cpink = '\x1b[38;2;236;72;153m';
let cred = '\x1b[38;2;220;20;60m';
let purple = (x, last = '\x1b[0m') => `${cpurple}${x}${last}`;
let pink = (x, last = '\x1b[0m') => `${cpink}${x}${last}`;
let red = (x, last = '\x1b[0m') => `${cred}[${x.toUpperCase()}]${last}`;

if (logLogs) {
  logs.push = function(x) {
    if (x.role === 'assistant') console.log(pink('> ' + x.content));
    else console.log(purple(x.content));
    console.log();
    return [].push.call(logs, x);
  };
}

let start = {
  model,
  simple: true,
  logs,
  tools: {
    lookAround: () => ({
      handler: ({ reason }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        logs.push({ role: 'user', content: `You see a ${red('locked door', cpurple)}, ${red('two statues', cpurple)}, and some ${red('debris', cpurple)}.` });
        return puzzle;
      },
    }),
  },
  choice: 'required',
};

let puzzle = {
  model,
  simple: true,
  logs,
  tools: {
    investigate: () => st.investigated.length < 3 && {
      parameters: {
        type: 'object',
        properties: { target: { type: 'string', enum: () => ['door', 'statues', 'debris'].filter(x => !st.investigated.includes(x)) } },
        required: ['target'],
      },
      handler: ({ reason, target }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        let lns = [];
        switch (target) {
          case 'door': {
            st.investigated.push('door');
            !st.door.oiled && lns.push(`The door is heavily dusted and could need some lubrication.`);
            if (st.door.open) lns.push(`The door is now open!`);
            else lns.push(`The door is locked shut.`);
            logs.push({ role: 'user', content: lns.join('\n') });
            break;
          }
          case 'statues': {
            st.investigated.push('statues');
            let lns = [];
            for (let x of ['lstatue', 'rstatue']) {
              x === 'lstatue' && lns.push(`To the ${red('left', cpurple)} you see the statue of an ${red('Eagle', cpurple)}.`);
              x === 'rstatue' && lns.push(`To the ${red('right', cpurple)} you see the statue of a ${red('Snake', cpurple)}.`);
              lns.push(`It is facing ${red(st[x].dir, cpurple)}.`);
              lns.push(st[x].lever ? `The inserted ${red('Wooden Rod', cpurple)} can be used as a lever to turn it.` : `A slot underneath could be used to insert a lever.`);
            }
            logs.push({ role: 'user', content: lns.join('\n') });
            break;
          }
          case 'debris': {
            st.investigated.push('debris');
            if (st.debris.picked) {
              logs.push({ role: 'user', content: `There's nothing unusual about the remaining debris.` });
              break;
            }
            st.inventory.push('wooden_rod', 'grease_can');
            st.debris.picked = true;
            logs.push({ role: 'user', content: `You found a ${red('Wooden Rod', cpurple)} and a ${red('Grease Can', cpurple)} amid the debris.` });
            break;
          }
        }
        return puzzle;
      },
    },
    lubeDoor: () => st.inventory.includes('grease_can') && {
      handler: ({ reason }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        st.door.oiled = true;
        st.inventory.splice(st.inventory.indexOf('grease_can'), 1);
        logs.push({ role: 'user', content: `The door hinges are now lubricated and could move freely.` });
        return puzzle;
      },
    },
    insertRod: () => st.inventory.includes('wooden_rod') && {
      parameters: {
        type: 'object',
        properties: { statue: { type: 'string', enum: ['lstatue', 'rstatue'] } },
        required: ['statue'],
      },
      handler: ({ reason, statue }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        st.inventory.splice(st.inventory.indexOf('wooden_rod'), 1);
        st[statue].lever = true;
        logs.push({ role: 'user', content: `You insert the ${red('Wooden Rod', cpurple)} in the ${red(statue === 'lstatue' ? 'Eagle Statue' : 'Snake Statue', cpurple)}.` });
        return puzzle;
      },
    },
    turnStatueClockwise: () => (st.lstatue.lever || st.rstatue.lever) && {
      parameters: {
        type: 'object',
        properties: { statue: { type: 'string', enum: () => ['lstatue', 'rstatue'].filter(x => st[x].lever) } },
        required: ['statue'],
      },
      handler: ({ reason, statue }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        if (!st[statue].lever) {
          logs.push({ role: 'user', content: `This statue doesn't have a lever to turn.` });
          return puzzle;
        }
        let lns = [];
        st[statue].dir = { left: 'up', up: 'right', right: 'down', down: 'left' }[st[statue].dir];
        lns.push(`You turn the ${red(statue === 'lstatue' ? 'Eagle Statue' : 'Snake Statue', cpurple)} and it's now facing ${red(st[statue].dir, cpurple)}.`);
        if (st.lstatue.dir === 'right' && st.rstatue.dir === 'left' && !st.statuesAligned) {
          st.inventory.push('door_key');
          lns.push(`The statues are now facing each other. ${red('Door Key', cpurple)} acquired!`);
        }
        logs.push({ role: 'user', content: lns.join('\n') });
        return puzzle;
      },
    },
    removeRod: () => (st.lstatue.lever || st.rstatue.lever) && {
      handler: ({ reason }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        st.inventory.push('wooden_rod');
        st.lstatue.lever = st.rstatue.lever = false;
        logs.push({ role: 'user', content: `You remove the ${red('Wooden Rod', cpurple)} from the statue.` });
        return puzzle;
      },
    },
    unlockDoor: () => st.inventory.includes('door_key') && {
      handler: ({ reason }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        if (!st.door.oiled) {
          logs.push({ role: 'user', content: `The door is full of dust and lacks lubrication.` });
          return puzzle;
        }
        st.inventory.splice(st.inventory.indexOf('door_key'), 1);
        st.door.open = true;
        logs.push({ role: 'user', content: `You unlocked the door!` });
        return puzzle;
      },
    },
    exit: () => st.door.open && {
      handler: ({ reason }) => {
        reason && logs.push({ role: 'assistant', content: reason });
        logs.push({ role: 'user', content: `You exit through the door and complete the puzzle!` });
        return 'end';
      },
    },
  },
  choice: 'required',
};

await looptools(start);

2-complete.js

import { inspect } from 'util';

let tap = x => (console.log(inspect(x, { depth: null, colors: true })), x);

function resolve(x) {
  if (typeof x === 'function') return x();
  let visited = new Set();
  function walk(value) {
    if (value && typeof value === 'object') {
      if (visited.has(value)) return;
      visited.add(value);
      for (let key of Object.keys(value)) {
        if (typeof value[key] === "function") value[key] = value[key]();
        walk(value[key]);
      }
    }
  }
  walk(x);
  return x;
}

let cfg = {
  oai: {
    endpoint: 'https://api.openai.com/v1/responses',
    apiKey: process.env.OPENAI_API_KEY,
  },
  oail: {
    endpoint: 'https://api.openai.com/v1/chat/completions',
    apiKey: process.env.OPENAI_API_KEY,
  },
  xai: {
    endpoint: 'https://api.x.ai/v1/chat/completions',
    apiKey: process.env.XAI_KEY,
  },
};

export default async function complete(logs, { model, n, rolemap, tools, choice, simple, signal } = {}) {
  let provmod = (model || 'xai:grok-2').split(':');
  let provider = provmod[0];
  model = provmod[1];
  let { endpoint, apiKey } = cfg[provider];
  let messages = logs.map(x => {
    if (!rolemap || /system|assistant|user/.test(x.role)) return { ...x, tools: undefined };
    return { role: null, ...x, role: rolemap[x.role], tools: undefined };
  }).filter(x => x.role !== 'drop');
  let tries = 1;
  if (choice === 'required') messages.unshift({ role: 'system', content: `Tool calling is MANDATORY.` });
  switch (provider) {
    case 'oai': {
      if (n != null) throw new Error(`OpenAI Responses API doesn't support parameter 'n'`);
      let ctools = [...Object.entries(tools || {})]
        .filter(xs => typeof xs[1] === 'function' ? xs[1]() : xs[1])
        .map(([name, spec]) => ({ type: 'function', name: null, parameters: {}, ...(typeof spec === 'function' ? spec() : spec), name, handler: undefined }))
        .map(spec => resolve(spec));
      for (let x of ctools) {
        x.parameters.type ??= 'object';
        x.parameters.properties ??= {};
        x.parameters.properties.reason ??= { type: 'string', description: `Describe why you're taking this action` };
        x.parameters.required ??= [];
        x.parameters.required.push('reason');
      }
      let cchoice = /^auto|required|none$/.test(choice) ? choice : (choice ? { type: 'function', name: choice } : 'auto');
      let payload = { model, input: messages, tools: ctools, tool_choice: cchoice };
      let res = await fetch(endpoint, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
        signal,
      });
      if (res.headers.get('Content-Type') === 'application/json') res = await res.json();
      else res = await res.text();
      if (typeof res === 'string') return [res.status, res];
      !res.output && console.log(inspect(res, { depth: null, colors: true }));
      res.output = await Promise.all(res.output.map(async x => {
        if (x.type !== 'function_call') return x;
        x.arguments = JSON.parse(x.arguments);
        let handler = tools[x.name]().handler;
        //console.log('calling:', x.name, x.arguments);
        if (!handler) return x;
        let result = await handler(x.arguments);
        if (result != null) x.result = result;
        return x;
      }));
      if (simple) {
        let choices = res.output.map(x => {
          if (x.type !== 'function_call') {
            x.content = x.content.map(x => x.text);
            return { role: x.role, content: x.content.length === 1 ? x.content[0] : x.content };
          }
          let ret = { role: 'assistant', tools: {} };
          ret.tools[x.name] = { arguments: x.arguments };
          if (x.result != null) ret.tools[x.name].result = x.result;
          return ret;
        });
        if (!choices.length) return null;
        if (choices.length === 1) return choices[0];
        return choices;
      }
      return res;
    }
    case 'oail': {
      let ctools = [...Object.entries(tools || {})]
        .filter(xs => typeof xs[1] === 'function' ? xs[1]() : xs[1])
        .filter(xs => xs[1])
        .map(([name, spec]) => ({ type: 'function', function: { name: null, parameters: {}, ...spec, name, handler: undefined } }))
        .map(spec => resolve(spec));
      let cchoice = /^auto|required|none$/.test(choice) ? choice : (choice ? { type: 'function', name: choice } : 'auto');
      let res = await fetch(endpoint, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${apiKey}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ n: n ?? 1, model, messages, tools: ctools, tool_choice: cchoice }),
        signal,
      });
      if (res.headers.get('Content-Type') === 'application/json') res = await res.json();
      else res = await res.text();
      if (typeof res === 'string') return [res.status, res];
      res.choices = await Promise.all(res.choices.map(async x => {
        x.message.content = x.message.content?.replaceAll?.(/\n+/, '\n')?.trim?.();
        if (!x.message.tool_calls) return x;
        x.message.tool_calls = await Promise.all(x.message.tool_calls.map(async y => {
          if (y.type !== 'function') return y;
          y.function.arguments = JSON.parse(y.function.arguments);
          let handler = tools[y.function.name].handler;
          //console.log('calling:', y.function.name, handler);
          let result = handler ? await handler(y.function.arguments) : y.function.arguments;
          if (result != null) y.function.result = result;
          return y;
        }));
        return x;
      }));
      if (simple) {
        let choices = res.choices.map(x => {
          let ret = x.message
          if (ret.tool_calls) {
            ret.tools = Object.fromEntries(ret.tool_calls.map(y => {
              if (y.type !== 'function') throw new Error(`Unknown tool call type: ${y.type}`);
              let { name } = y.function;
              delete y.function.name;
              return [name, y.function];
            }));
            delete ret.tool_calls;
          }
          delete ret.annotations;
          delete ret.refusal;
          return ret;
        });
        if (!choices.length) return null;
        if (choices.length === 1) return choices[0];
        return choices;
      }
      return res;
    }
    case 'xai': {
      let ctools = [...Object.entries(tools || {})]
        .filter(xs => typeof xs[1] === 'function' ? xs[1]() : xs[1])
        .filter(xs => xs[1])
        .map(([name, spec]) => ({ type: 'function', function: { name: null, parameters: {}, ...(typeof spec === 'function' ? spec() : spec), name, handler: undefined } }))
        .map(spec => resolve(spec));
      let cchoice = /^auto|required|none$/.test(choice) ? choice : (choice ? { type: 'function', name: choice } : 'auto');
      let payload = { n: n ?? 1, model, messages, tools: ctools, tool_choice: cchoice === 'required' ? 'auto' : cchoice };
      cchoice === 'required' && tries > 1 && messages.push({ role: 'system', content: `You have failed to produce a mandatory tool call (#${tries}, ${crypto.randomUUID()}).` });
      let fncall = false;
      while (true) {
        let res = await fetch(endpoint, {
          method: 'POST',
          headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify(payload),
          signal,
        });
        if (res.headers.get('Content-Type') === 'application/json') res = await res.json();
        else res = await res.text();
        if (typeof res === 'string') return [res.status, res];
        !res.choices && console.log(res, inspect(payload, { depth: null, colors: true }));
        res.choices = await Promise.all(res.choices.map(async x => {
          x.message.content = x.message.content?.replaceAll?.('<has_function_call>', '')?.replaceAll?.(/\n+/g, '\n')?.trim?.();
          if (!x.message.tool_calls) return x;
          x.message.tool_calls = await Promise.all(x.message.tool_calls.map(async y => {
            if (y.type !== 'function') return y;
            y.function.arguments = JSON.parse(y.function.arguments);
            y.function.arguments.reason = x.message.content;
            let handler = tools[y.function.name]().handler;
            //console.log('calling:', y.function.name, y.function.arguments);
            let result = handler ? await handler(y.function.arguments) : y.function.arguments;
            if (result != null) y.function.result = result;
            fncall = true;
            return y;
          }));
          return x;
        }));
        if (cchoice === 'required' && !fncall) {
          console.log(`Tool call failed with message:`, res.choices[0].message.content);
          console.log();
          await new Promise(pres => setTimeout(pres, 1000));
          tries++;
          continue;
        }
        if (simple) {
          let choices = res.choices.map(x => {
            let ret = x.message
            if (ret.tool_calls) {
              ret.tools = Object.fromEntries(ret.tool_calls.map(y => {
                if (y.type !== 'function') throw new Error(`Unknown tool call type: ${y.type}`);
                let { name } = y.function;
                delete y.function.name;
                return [name, y.function];
              }));
              delete ret.tool_calls;
            }
            delete ret.refusal;
            return ret;
          });
          if (!choices.length) return null;
          if (choices.length === 1) return choices[0];
          return choices;
        }
        return res;
      }
    }
  }
};