openAgent

1import { describe, expect, test } from "bun:test"
2import { Effect, Schema } from "effect"
3import { CodeMode, Tool } from "../src/index.js"
4 
5// Key enumeration: Object.keys and for...in share one surface over plain objects, arrays
6// (index strings), and tool references (namespace/tool names from the host tool tree), so a
7// model can discover what it may call instead of guessing names from the instructions. The
8// motivating transcript: `Object.keys(tools)` failed with the generic plain-objects-only
9// message and `for (const key in tools)` was unsupported syntax, forcing blind guesses.
10 
11const echo = (description: string) =>
12  Tool.make({
13    description,
14    input: Schema.Struct({ value: Schema.String }),
15    output: Schema.String,
16    run: ({ value }) => Effect.succeed(value),
17  })
18 
19const tools = {
20  github: { list_issues: echo("List issues"), get_issue: echo("Get one issue") },
21  memory: { search: echo("Search memory") },
22  playwright: { navigate: echo("Navigate somewhere") },
23}
24 
25const run = (code: string) => Effect.runPromise(CodeMode.execute({ tools, code }))
26const value = async (code: string) => {
27  const result = await run(code)
28  if (!result.ok) throw new Error(`expected success, got ${result.error.kind}: ${result.error.message}`)
29  return result.value
30}
31const error = async (code: string) => {
32  const result = await run(code)
33  if (result.ok) throw new Error(`expected failure, got value ${JSON.stringify(result.value)}`)
34  return result.error
35}
36 
37describe("Object.keys over tool references", () => {
38  test("enumerates top-level namespaces (the transcript program)", async () => {
39    expect(
40      await value(`
41      const namespaces = Object.keys(tools)
42      return { namespaces, count: namespaces.length }
43    `),
44    ).toEqual({ namespaces: ["github", "memory", "playwright", "$codemode"], count: 4 })
45  })
46 
47  test("enumerates tool names at a nested namespace", async () => {
48    expect(await value(`return Object.keys(tools.github)`)).toEqual(["list_issues", "get_issue"])
49  })
50 
51  test("a callable tool is a leaf and enumerates as []", async () => {
52    expect(await value(`return Object.keys(tools.github.list_issues)`)).toEqual([])
53  })
54 
55  test("the internal discovery namespace enumerates its callable surface", async () => {
56    expect(await value(`return Object.keys(tools.$codemode)`)).toEqual(["search"])
57  })
58 
59  test("an unknown namespace is an UnknownTool error pointing at the discovery idioms", async () => {
60    const failure = await error(`return Object.keys(tools.nonexistent)`)
61    expect(failure.kind).toBe("UnknownTool")
62    expect(failure.message).toContain("Unknown tool namespace 'nonexistent'")
63    expect(failure.suggestions?.join(" ")).toContain("Object.keys(tools)")
64  })
65 
66  test("Object.values/entries on a tool reference explain the working idioms", async () => {
67    for (const method of ["values", "entries"] as const) {
68      const failure = await error(`return Object.${method}(tools)`)
69      expect(failure.kind).toBe("InvalidDataValue")
70      expect(failure.message).toContain(
71        `Object.${method}(...) cannot read tool references: they are not plain data. Use Object.keys(tools) for names, or tools.$codemode.search({ query }) for signatures.`,
72      )
73    }
74    const nested = await error(`return Object.entries(tools.github)`)
75    expect(nested.message).toContain("Use Object.keys(tools) for names")
76  })
77})
78 
79describe("Object.keys over arrays", () => {
80  test("returns index strings, like JS", async () => {
81    expect(await value(`return Object.keys(["a", "b", "c"])`)).toEqual(["0", "1", "2"])
82    expect(await value(`return Object.keys([])`)).toEqual([])
83  })
84 
85  test("objects keep their own enumerable keys", async () => {
86    expect(await value(`return Object.keys({ a: 1, b: 2 })`)).toEqual(["a", "b"])
87  })
88 
89  test("non-object inputs still fail clearly", async () => {
90    const failure = await error(`return Object.keys("nope")`)
91    expect(failure.message).toContain("Object.keys expects a data object or array")
92  })
93})
94 
95describe("for...in", () => {
96  test("iterates own enumerable keys of a plain object with break/continue", async () => {
97    expect(
98      await value(`
99      const seen = []
100      for (const key in { a: 1, b: 2, c: 3, d: 4 }) {
101        if (key === "b") continue
102        if (key === "d") break
103        seen.push(key)
104      }
105      return seen
106    `),
107    ).toEqual(["a", "c"])
108  })
109 
110  test("iterates index strings over arrays", async () => {
111    expect(
112      await value(`
113      const indexes = []
114      for (const i in ["x", "y", "z"]) {
115        if (i === "2") break
116        indexes.push(i)
117      }
118      return indexes
119    `),
120    ).toEqual(["0", "1"])
121  })
122 
123  test("supports let declarations and bare identifiers", async () => {
124    expect(
125      await value(`
126      let last = ""
127      for (let key in { a: 1, b: 2 }) last = key
128      return last
129    `),
130    ).toBe("b")
131    expect(
132      await value(`
133      let key = "before"
134      for (key in { only: 1 }) {}
135      return key
136    `),
137    ).toBe("only")
138  })
139 
140  test("enumerates namespaces and tools from the callable tool tree", async () => {
141    expect(
142      await value(`
143      const names = []
144      for (const ns in tools) {
145        for (const name in tools[ns]) names.push(ns + "." + name)
146      }
147      return names
148    `),
149    ).toEqual(["github.list_issues", "github.get_issue", "memory.search", "playwright.navigate", "$codemode.search"])
150  })
151 
152  test("unsupported values fail with a hint at for...of and Object.keys", async () => {
153    for (const expression of [`"text"`, "new Map([[1, 2]])", "new Set([1])", "42", "null"]) {
154      const failure = await error(`for (const key in ${expression}) {}; return "no"`)
155      expect(failure.message).toContain("for...in requires a plain object, array, or tools reference")
156      expect(failure.message).toContain("Use for...of for arrays/strings/Maps/Sets, or Object.keys(value)")
157    }
158  })
159})
160