traw 0.2.1

package/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release Traw
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  publish-npm:
+    name: Publish to NPM
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Get version
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Update package version
+        run: npm version ${{ steps.version.outputs.VERSION }} --no-git-tag-version --allow-same-version
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile --ignore-scripts
+
+      - name: Publish to NPM
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  release:
+    name: Create Release
+    needs: [publish-npm]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get version
+        id: version
+        run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          name: Traw v${{ steps.version.outputs.VERSION }}
+          body: |
+            ## Traw v${{ steps.version.outputs.VERSION }}
+
+            AI browser agent for terminal.
+
+            ### Installation
+
+            ```bash
+            # bun (recommended)
+            bun add -g traw
+
+            # npm
+            npm install -g traw
+            ```
+
+            ### Usage
+
+            ```bash
+            traw auth
+            traw run "find weather in Moscow"
+            traw --help
+            ```
+
+            ### Check for updates
+
+            ```bash
+            traw upd
+            ```
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.gitmodules

@@ -0,0 +1,6 @@
+[submodule "markdownly.js"]
+	path = markdownly.js
+	url = https://github.com/zarazaex69/markdownly.js.git
+[submodule "mo"]
+	path = mo
+	url = https://github.com/zarazaex69/mo.git

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, zarazaex
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/bun.lock

@@ -0,0 +1,41 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "traw",
+      "dependencies": {
+        "markdownly.js": "^1.1.0",
+        "playwright": "^1.52.0",
+        "zod": "^4.2.1",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+
+    "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
+
+    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
+    "markdownly.js": ["markdownly.js@1.1.0", "", { "bin": { "markdown": "dist/cli.js", "md": "dist/cli.js" } }, "sha512-OfSC5OlL7sbeExYRjJFNZzSpk8KQqZAQL9mbkrglqUOGWu9NEkIEPbqbgp+lnfcl8KgTeeAHvkpCRzNNFj0LhQ=="],
+
+    "playwright": ["playwright@1.57.0", "", { "dependencies": { "playwright-core": "1.57.0" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-ilYQj1s8sr2ppEJ2YVadYBN0Mb3mdo9J0wQ+UuDhzYqURwSoW4n1Xs5vs7ORwgDGmyEh33tRMeS8KhdkMoLXQw=="],
+
+    "playwright-core": ["playwright-core@1.57.0", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+
+    "zod": ["zod@4.2.1", "", {}, "sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw=="],
+  }
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "traw",
+  "version": "0.2.1",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "traw": "./src/cli/index.ts"
+  },
+  "scripts": {
+    "traw": "bun run src/cli/index.ts",
+    "postinstall": "bunx playwright install firefox"
+  },
+  "dependencies": {
+    "markdownly.js": "^1.1.0",
+    "playwright": "^1.52.0",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/readme.md

@@ -0,0 +1,63 @@
+<div align="center">
+  <img src="assets/logo.png" alt="Traw" width="300"/>
+</div>
+
+<div align="center">
+
+![Bun](https://img.shields.io/badge/-Bun-0D1117?style=flat-square&logo=Bun&logoColor=F3E6D8)
+![License](https://img.shields.io/badge/license-BSD--3--Clause-0D1117?style=flat-square&logo=open-source-initiative&logoColor=green&labelColor=0D1117)
+
+
+<details>
+<summary>🚨 Warning </summary>
+This project uses reverse engineering api z.ai, do not use it for anything because of serious/personal data, it is just a toy - not a tool 
+<br/>
+Plz Give Star
+</details>
+
+</div>
+
+
+## About
+Traw is a simple and fast neuro agent that browses the internet instead of you
+
+<div align="center">
+  <img src="assets/expirience.png" alt="auth" style="border-radius: 9px;"/>
+</div>
+
+## Fast Start
+
+
+```bash
+# install the traw
+git clone https://github.com/zarazaex69/traw
+cd traw
+bun install
+
+# auth the traw 
+bun run traw auth
+ # mo server not found. install mo? [Y/n] Y 
+```
+<div align="center">
+  <img src="assets/auth.gif" alt="auth" style="border-radius: 9px;"/>
+</div>
+
+```bash
+ # start the traw
+bun run traw run "your goal"
+```
+
+<div align="center">
+
+---
+
+### Contact
+
+Telegram: [zarazaex](https://t.me/zarazaexe)
+<br>
+Email: [zarazaex@tuta.io](mailto:zarazaex@tuta.io)
+<br>
+Site: [zarazaex.xyz](https://zarazaex.xyz)
+<br>
+
+</div>

package/src/agent/agent.ts

@@ -0,0 +1,207 @@
+import type { Action, AgentConfig, AgentStep, ChatMessage, PageState } from "../types"
+import { BrowserController } from "../browser/controller"
+import { MoClient } from "../api/mo-client"
+import { log } from "../utils/log"
+import { checkNotify, notify } from "../utils/notify"
+import { systemPrompt, planningPrompt } from "./prompts"
+
+export class Agent {
+  private browser: BrowserController
+  private mo: MoClient
+  private config: AgentConfig
+  private history: AgentStep[] = []
+  private messages: ChatMessage[] = []
+  private plan = ""
+
+  private aiTime = 0
+  private browserTime = 0
+  private startTime = 0
+
+  constructor(config: AgentConfig) {
+    this.config = config
+    this.browser = new BrowserController(config)
+    this.mo = new MoClient({
+      moUrl: config.moUrl,
+      apiUrl: config.apiUrl,
+      apiKey: config.apiKey,
+      model: config.model,
+      thinking: config.thinking,
+    })
+  }
+
+  async run(goal: string): Promise<{ history: AgentStep[]; video: string | null }> {
+    this.startTime = Date.now()
+
+    await checkNotify()
+
+    if (this.config.thinking) {
+      const planStart = Date.now()
+      log.planning()
+      this.plan = await this.createPlan(goal)
+      this.aiTime += Date.now() - planStart
+      log.planDone()
+      log.plan(this.plan)
+    }
+
+    log.openStart()
+    await this.browser.launch()
+    await this.browser.execute({
+      type: "goto",
+      text: "https://html.duckduckgo.com/html/",
+      reason: "start page",
+    })
+    log.openStop()
+
+    this.messages.push({ role: "system", content: systemPrompt })
+
+    const taskMessage = this.plan
+      ? `Your task: ${goal}\n\nYour plan:\n${this.plan}\n\nYou have ${this.config.maxSteps} steps maximum. Be efficient. You are now on DuckDuckGo search.`
+      : `Your task: ${goal}\n\nYou have ${this.config.maxSteps} steps maximum. Be efficient. You are now on DuckDuckGo search.`
+    this.messages.push({ role: "user", content: taskMessage })
+
+    let finalReason = ""
+
+    try {
+      for (let step = 0; step < this.config.maxSteps; step++) {
+        const loadStart = Date.now()
+        log.loadStart()
+        const state = await this.browser.getState()
+        log.loadStop()
+        this.browserTime += Date.now() - loadStart
+
+        log.step(step + 1, this.config.maxSteps, state.url)
+
+        const thinkStart = Date.now()
+        log.receiveStart()
+        const decision = await this.think(state)
+        log.receiveStop()
+        this.aiTime += Date.now() - thinkStart
+
+        log.thought(decision.thought)
+        const target = decision.action.index !== undefined 
+          ? `[${decision.action.index}] ${decision.action.text || ""}`
+          : decision.action.text
+        log.action(decision.action.type, target)
+
+        const execStart = Date.now()
+        const result = await this.browser.execute(decision.action)
+        this.browserTime += Date.now() - execStart
+
+        if (result.startsWith("error:")) {
+          log.fail(result)
+        } else {
+          log.ok()
+        }
+
+        this.history.push({
+          timestamp: Date.now(),
+          thought: decision.thought,
+          action: decision.action,
+          result,
+        })
+
+        if (decision.action.type === "done") {
+          finalReason = decision.action.reason
+          break
+        }
+
+        if (decision.action.type === "back") {
+          step = Math.max(-1, step - 2)
+        }
+
+        await new Promise((r) => setTimeout(r, 300))
+      }
+    } finally {
+      const videoPath = await this.browser.close()
+      const totalTime = Date.now() - this.startTime
+      log.done(this.history.length, finalReason)
+      log.stats(totalTime, this.aiTime, this.browserTime)
+
+      await notify("Agent done", `${this.history.length} steps completed`)
+
+      return { history: this.history, video: videoPath }
+    }
+  }
+
+  private async createPlan(goal: string): Promise<string> {
+    return this.mo.chat([
+      { role: "system", content: planningPrompt },
+      { role: "user", content: `Goal: ${goal}\nMax steps available: ${this.config.maxSteps}` },
+    ])
+  }
+
+  private formatRecentHistory(): string {
+    if (this.history.length === 0) return ""
+    
+    const lines = this.history.map((h, i) => {
+      return `${i + 1}. ${h.action.type}${h.action.index !== undefined ? ` [${h.action.index}]` : ""}${h.action.text ? ` "${h.action.text}"` : ""} → ${h.result}`
+    })
+    
+    return `\nPrevious actions:\n${lines.join("\n")}`
+  }
+
+  private async think(state: PageState): Promise<{ thought: string; action: Action }> {
+    const historyBlock = this.formatRecentHistory()
+    
+    const stateText = `URL: ${state.url}
+Title: ${state.title}
+${historyBlock}
+
+Elements:
+${state.text}
+
+What's your next action?`
+
+    if (this.config.debug) {
+      console.log("\n" + state.text)
+    }
+
+    this.messages.push({ role: "user", content: stateText })
+
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const response = await this.mo.chat(this.messages)
+      const parsed = this.parseResponse(response)
+
+      if (parsed) {
+        this.messages.push({ role: "assistant", content: response })
+        return parsed
+      }
+
+      if (attempt < 2) {
+        log.fail(`parse error, retry ${attempt + 2}/3`)
+        this.messages.push({ role: "assistant", content: response })
+        this.messages.push({ role: "user", content: "Invalid JSON. Reply with valid JSON only, no markdown." })
+      }
+    }
+
+    return {
+      thought: "failed to parse response",
+      action: { type: "wait", reason: "parse error" },
+    }
+  }
+
+  private parseResponse(response: string): { thought: string; action: Action } | null {
+    try {
+      let jsonStr = response
+
+      const match = response.match(/```(?:json)?\s*([\s\S]*?)```/)
+      if (match) {
+        jsonStr = match[1]
+      }
+
+      const parsed = JSON.parse(jsonStr.trim())
+      if (!parsed.action?.type) return null
+
+      return {
+        thought: parsed.thought || "thinking...",
+        action: parsed.action,
+      }
+    } catch (err) {
+      const logEntry = `\n--- ${new Date().toISOString()} ---\nError: ${err}\nResponse:\n${response}\n`
+      import("fs").then(fs => {
+        fs.appendFileSync("agent-errors.log", logEntry)
+      }).catch(() => {})
+      return null
+    }
+  }
+}

package/src/agent/prompts.ts

@@ -0,0 +1,45 @@
+export const systemPrompt = `You a Traw -control a browser via DOM elements. Each element has an index [N].
+
+LANGUAGE RULES (STRICT):
+- "thought" field: ALWAYS in English, no exceptions
+- "done" action "reason" field: ALWAYS in the SAME language as user's original query
+  - If user asked in Russian → answer in Russian
+  - If user asked in English → answer in English
+  - Match the user's language exactly
+
+MARKDOWN FORMATTING (for "done" reason field):
+The terminal supports rich markdown rendering. USE these features for better readability:
+- **Headers**: Use ### for sections (e.g., ### Installation)
+- **Bold**: Use **text** for emphasis
+- **Italic**: Use *text* for subtle emphasis  
+- **Lists**: Use * or - for bullet points, 1. 2. 3. for numbered lists
+- **Code**: Use \`inline code\` for commands, \`\`\`lang for code blocks
+- **Links**: Use [text](url) format - they will be clickable
+- **Blockquotes**: Use > for quotes or important notes
+Structure your answers with headers and lists for easy scanning.
+
+ACTIONS (use index to target elements):
+- click: {"type":"click","index":N} - click element [N]
+- type: {"type":"type","index":N,"text":"query"} - type into input [N]
+- scroll: {"type":"scroll","direction":"down"} - scroll page
+- goto: {"type":"goto","text":"url"} - navigate to URL
+- wait: {"type":"wait"} - wait 2 seconds
+- back: {"type":"back"} - go back to previous page (FREE action, gives +1 step back, use when current page is wrong/useless)
+- done: {"type":"done","reason":"result"} - task complete, include answer IN USER'S LANGUAGE with markdown
+
+OUTPUT (JSON only, no markdown wrapper):
+{"thought":"English reasoning here","action":{"type":"click","index":0}}`
+
+export const planningPrompt = `Create short numbered plan to accomplish goal via browser. Start from DuckDuckGo search.
+
+IMPORTANT: Plan must fit within the given step limit. Each navigation/click/type = 1 step.
+- If max steps is low (5-10): be very direct, skip optional steps
+- If max steps is high (20+): can be more thorough
+
+LANGUAGE RULES:
+- Plan steps: ALWAYS write in English
+- Final answer (when task is done): Write in the SAME language as user's query
+
+MARKDOWN: You may use markdown in plan (headers, lists, bold) for better terminal rendering.
+
+No JSON in plan.`

package/src/api/mo-client.ts

@@ -0,0 +1,62 @@
+import type { ChatMessage } from "../types"
+
+export interface MoClientOptions {
+  moUrl: string
+  apiUrl?: string
+  apiKey?: string
+  model: string
+  thinking: boolean
+}
+
+export class MoClient {
+  private url: string
+  private apiKey?: string
+  private model: string
+  private thinking: boolean
+
+  constructor(opts: MoClientOptions) {
+    // custom api takes priority over mo
+    this.url = opts.apiUrl || opts.moUrl
+    this.apiKey = opts.apiKey
+    this.model = opts.model
+    this.thinking = opts.thinking
+  }
+
+  async chat(messages: ChatMessage[]): Promise<string> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    }
+
+    if (this.apiKey) {
+      headers["Authorization"] = `Bearer ${this.apiKey}`
+    }
+
+    const resp = await fetch(`${this.url}/v1/chat/completions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        stream: false,
+        thinking: this.thinking,
+      }),
+    })
+
+    if (!resp.ok) {
+      const body = await resp.text()
+      throw new Error(`mo error: ${resp.status} ${body}`)
+    }
+
+    const data = (await resp.json()) as {
+      choices: { message: { content: string }; finish_reason: string }[]
+    }
+
+    // debug: check if response was truncated
+    const finish = data.choices[0]?.finish_reason
+    if (finish && finish !== "stop") {
+      console.warn(`[mo] finish_reason: ${finish} (response may be truncated)`)
+    }
+
+    return data.choices[0]?.message?.content ?? ""
+  }
+}