Sessions

import { FileSessionManager, OpenAIProvider, createLocalAgent, tool } from 'astorlm'
import { z } from 'zod'

const talkTo = tool({
  name: 'talk_to',
  description: 'Talk to someone in town. Returns what they say.',
  schema: z.object({ npc: z.string() }),
  execute: async ({ npc }) => town.talk(npc), // your code
})

const buy = tool({
  name: 'buy',
  description: 'Buy an item at the shop. Returns the price and the gold left.',
  schema: z.object({ item: z.string() }),
  execute: async ({ item }) => shop.buy(item), // your code
})

// The adventure log: quest-1.jsonl (one message per line) and quest-1.meta.json, in this folder.
const sessionManager = new FileSessionManager({ dir: './sessions' })

const quest = (sessionId: string) =>
  createLocalAgent({
    // Any OpenAI-compatible endpoint: OpenAI, Ollama, LM Studio, vLLM, a proxy…
    provider: new OpenAIProvider({
      baseURL: 'http://localhost:11434/v1', // e.g. Ollama's default address
      model: 'your-model', // e.g. 'llama3.1', 'gpt-4o-mini'
      apiKey: 'YOUR_API_KEY', // local servers usually ignore it
    }),
    tools: [talkTo, buy],
    sessionId, // a new id starts an empty log; a known one loads it
    sessionManager,
  })

// Day 1. Every message is saved as soon as it's added, so a crash loses nothing.
const day1 = await quest('quest-1')
await day1.run('I need to get into the Cave of Echoes. Find out what it takes, and get what you can.')

// …the process ends. Day 2: a new agent on the same id reads the log back before answering.
const day2 = await quest('quest-1')
console.log(day2.getMessages().length) // 6: yesterday is in the history
await day2.run('I got the Silver Key from the mayor’s daughter. What now?')

// A fork: a new session with a copy of every message. quest-1 stays as it was.
const west = await day2.fork({ newSessionId: 'quest-2' })
await west.run('Suppose the key doesn’t fit. Is there another way in?')

// Sessions from scratch: a JSONL file per conversation. Node's standard library only.
import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'

type Message = { role: string; content: unknown; [key: string]: unknown }
const DIR = './sessions'
const pathOf = (id: string) => `${DIR}/${id}.jsonl`

// 1. Load: one JSON message per line. No file yet means a new, empty session.
export function load(id: string): Message[] {
  if (!existsSync(pathOf(id))) return []
  return readFileSync(pathOf(id), 'utf8')
    .split('\n')
    .filter(Boolean)
    .map((line) => JSON.parse(line))
}

// 2. Save as you go: append each message the moment it exists. A crash mid-run loses nothing.
function append(id: string, message: Message): void {
  mkdirSync(DIR, { recursive: true })
  appendFileSync(pathOf(id), JSON.stringify(message) + '\n')
}

// 3. Fork: copy the file. From here on, each session only appends to its own.
export function fork(from: string, to: string): void {
  copyFileSync(pathOf(from), pathOf(to))
}

// 4. The loop from level 2, with its history loaded first and every new message written down.
export async function runSession(id: string, prompt: string, maxTurns = 10): Promise<string> {
  const messages = load(id)
  const add = (message: Message) => {
    messages.push(message)
    append(id, message)
  }

  add({ role: 'user', content: prompt })
  for (let turn = 1; turn <= maxTurns; turn++) {
    const choice = await chat(messages) // one model call, as in level 2
    add(choice.message)
    if (choice.finish_reason !== 'tool_calls') return choice.message.content ?? ''
    for (const call of choice.message.tool_calls ?? []) {
      add({ role: 'tool', tool_call_id: call.id, content: await runTool(call) })
    }
  }
  throw new Error(`No answer after ${maxTurns} turns`)
}

// Day 1, then day 2 on the same id, then a fork to try another way.
await runSession('quest-1', 'I need to get into the Cave of Echoes. Find out what it takes, and get what you can.')
await runSession('quest-1', 'I got the Silver Key from the mayor’s daughter. What now?')
fork('quest-1', 'quest-2')
await runSession('quest-2', 'Suppose the key doesn’t fit. Is there another way in?')

# Sessions from scratch: a JSONL file per conversation. Standard library only.
import json
import shutil
from pathlib import Path

DIR = Path("sessions")


def path_of(session_id):
    return DIR / f"{session_id}.jsonl"


# 1. Load: one JSON message per line. No file yet means a new, empty session.
def load(session_id):
    path = path_of(session_id)
    if not path.exists():
        return []
    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line]


# 2. Save as you go: append each message the moment it exists. A crash mid-run loses nothing.
def append(session_id, message):
    DIR.mkdir(exist_ok=True)
    with path_of(session_id).open("a", encoding="utf-8") as log:
        log.write(json.dumps(message) + "\n")


# 3. Fork: copy the file. From here on, each session only appends to its own.
def fork(source, target):
    shutil.copyfile(path_of(source), path_of(target))


# 4. The loop from level 2, with its history loaded first and every new message written down.
def run_session(session_id, prompt, max_turns=10):
    messages = load(session_id)

    def add(message):
        messages.append(message)
        append(session_id, message)

    add({"role": "user", "content": prompt})
    for _ in range(max_turns):
        choice = chat(messages)  # one model call, as in level 2
        add(choice["message"])
        if choice["finish_reason"] != "tool_calls":
            return choice["message"].get("content") or ""
        for call in choice["message"].get("tool_calls", []):
            add({"role": "tool", "tool_call_id": call["id"], "content": run_tool(call)})

    raise RuntimeError(f"No answer after {max_turns} turns")


# Day 1, then day 2 on the same id, then a fork to try another way.
run_session("quest-1", "I need to get into the Cave of Echoes. Find out what it takes, and get what you can.")
run_session("quest-1", "I got the Silver Key from the mayor's daughter. What now?")
fork("quest-1", "quest-2")
run_session("quest-2", "Suppose the key doesn't fit. Is there another way in?")