@agentrq/agentrq-ws 0.7.0

package/src/help.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+import { COMMANDS } from './commands.js'
+import { VERSION } from './version.js'
+
+export const GLOBAL_OPTIONS = {
+  json: { type: 'boolean', description: 'Print the raw JSON result instead of text' },
+  server: { type: 'string', description: 'Which server in .mcp.json to use' },
+  config: { type: 'string', description: 'Path to an .mcp.json (default: nearest one upwards)' },
+  help: { type: 'boolean', short: 'h', description: 'Show help for a command' },
+  version: { type: 'boolean', short: 'V', description: 'Print the version' },
+}
+
+const pad = (text, width) => text + ' '.repeat(Math.max(0, width - text.length))
+
+function renderOptions(options) {
+  const entries = Object.entries(options || {})
+  if (entries.length === 0) return ''
+  const rendered = entries.map(([name, spec]) => {
+    const flags = `--${name}${spec.short ? `, -${spec.short}` : ''}${spec.type === 'string' ? ' <value>' : ''}`
+    return [flags, spec.description || '']
+  })
+  const width = Math.max(...rendered.map(([flags]) => flags.length))
+  return rendered.map(([flags, description]) => `  ${pad(flags, width)}  ${description}`).join('\n')
+}
+
+/** Help for one command. */
+export function commandHelp(command) {
+  const lines = [command.summary, '', `Usage: ${command.usage}`]
+  const options = renderOptions(command.options)
+  if (options) lines.push('', 'Options:', options)
+  lines.push('', 'Global options:', renderOptions(GLOBAL_OPTIONS))
+  return lines.join('\n')
+}
+
+/** Help for a family of commands, such as `task` or `memory`. */
+export function groupHelp({ segments, members }) {
+  const name = segments.join(' ')
+  const width = Math.max(...members.map((c) => c.path.join(' ').length))
+  const list = members.map((c) => `  ${pad(c.path.join(' '), width)}  ${c.summary}`).join('\n')
+  return [
+    `Usage: agentrq-ws ${name} <command>`,
+    '',
+    `Commands:`,
+    list,
+    '',
+    `Run \`agentrq-ws help ${name} <command>\` for one of them.`,
+  ].join('\n')
+}
+
+/** The top-level help, generated from the command table so it cannot go stale. */
+export function mainHelp() {
+  const width = Math.max(...COMMANDS.map((c) => c.path.join(' ').length))
+  const list = COMMANDS.map((c) => `  ${pad(c.path.join(' '), width)}  ${c.summary}`).join('\n')
+  return `agentrq-ws ${VERSION} — AgentRQ workspace client
+
+Drives the workspace named by the .mcp.json in the current directory (or the
+nearest one above it), using the same tools an agent would, without spending an
+agent's tokens to do it.
+
+Usage: agentrq-ws <command> [options]
+
+Commands:
+${list}
+  ${pad('help', width)}  Show this help, or help for a command
+
+Global options:
+${renderOptions(GLOBAL_OPTIONS)}
+
+Text arguments accept @path to read a file and - to read stdin.
+Attachments are given as plain file paths; downloads are written to disk and
+the path is printed. You never handle base64.
+
+Examples:
+  agentrq-ws workspace
+  agentrq-ws task next
+  agentrq-ws task create "Ship the CLI" --body @notes.md --attach ./diagram.png
+  agentrq-ws reply 0isnjTCkpW5 "Done — logs attached" --attach ./run.log
+  agentrq-ws attachment get att-42 --task 0isnjTCkpW5 --out ~/Downloads
+  agentrq-ws memory load
+  echo "the full note" | agentrq-ws memory save release-notes.md --content -
+
+Environment:
+  AGENTRQ_WS_URL     Use this server URL instead of reading .mcp.json
+  AGENTRQ_WS_SERVER  Which server in .mcp.json to use`
+}

package/src/index.js

@@ -0,0 +1,8 @@
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+export { run } from './cli.js'
+export { McpClient, PROTOCOL_VERSION } from './mcp.js'
+export { resolveServer } from './config.js'
+export { COMMANDS } from './commands.js'
+export { VERSION } from './version.js'

package/src/mcp.js

@@ -0,0 +1,237 @@
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+import { ServerError } from './errors.js'
+import { VERSION } from './version.js'
+
+/**
+ * The revision to negotiate with. The workspace server is deliberately
+ * stateful, which means the go-sdk never offers 2026-07-28 there; it advertises
+ * 2025-11-25 down to 2024-11-05. 2025-06-18 sits safely inside that range and
+ * is the revision that introduced the MCP-Protocol-Version header, so it is
+ * what this client speaks.
+ */
+export const PROTOCOL_VERSION = '2025-06-18'
+
+const CLIENT_INFO = { name: 'agentrq-ws', version: VERSION }
+
+/**
+ * Pull the JSON-RPC payload out of a response body.
+ *
+ * Streamable HTTP is allowed to answer a POST with either a bare JSON object or
+ * an SSE stream carrying the same object in a `data:` frame, and the workspace
+ * server uses the SSE form. Handling only one of the two is the difference
+ * between working and "undefined result" with nothing in the logs.
+ */
+export function parseResponseBody(body, contentType = '') {
+  const text = String(body).trim()
+  if (text === '') return null
+
+  if (contentType.includes('text/event-stream') || text.startsWith('event:') || text.startsWith('data:')) {
+    const payloads = []
+    for (const line of text.split(/\r?\n/)) {
+      if (!line.startsWith('data:')) continue
+      const chunk = line.slice(5).trim()
+      if (chunk === '' || chunk === '[DONE]') continue
+      try {
+        payloads.push(JSON.parse(chunk))
+      } catch {
+        // A frame that is not JSON is not ours; keep looking.
+      }
+    }
+    if (payloads.length === 0) return null
+    // The last frame carrying a result or error is the answer to our call;
+    // earlier frames may be progress notifications.
+    for (let i = payloads.length - 1; i >= 0; i -= 1) {
+      if (payloads[i] && (payloads[i].result !== undefined || payloads[i].error !== undefined)) {
+        return payloads[i]
+      }
+    }
+    return payloads[payloads.length - 1]
+  }
+
+  try {
+    return JSON.parse(text)
+  } catch {
+    throw new ServerError(`server sent a non-JSON response: ${truncate(text, 200)}`)
+  }
+}
+
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max)}…` : text
+}
+
+/** Flatten a tool result's content blocks into plain text. */
+export function contentToText(result) {
+  if (!result) return ''
+  const blocks = Array.isArray(result.content) ? result.content : []
+  return blocks
+    .map((block) => {
+      if (!block) return ''
+      if (typeof block.text === 'string') return block.text
+      if (block.type === 'resource' && block.resource && typeof block.resource.text === 'string') {
+        return block.resource.text
+      }
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+/**
+ * A minimal streamable-HTTP MCP client.
+ *
+ * Deliberately hand-rolled rather than pulling in the MCP SDK: this is a CLI
+ * people run with `npx`, and three POSTs of handshake are cheaper to install
+ * and to audit than a dependency tree.
+ */
+export class McpClient {
+  constructor({ url, headers = {}, fetchImpl = globalThis.fetch, protocolVersion = PROTOCOL_VERSION }) {
+    this.url = url
+    this.extraHeaders = headers
+    this.fetchImpl = fetchImpl
+    this.protocolVersion = protocolVersion
+    this.sessionId = null
+    this.initialized = false
+    this.nextId = 1
+  }
+
+  headersFor(extra = {}) {
+    const headers = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      ...this.extraHeaders,
+      ...extra,
+    }
+    if (this.sessionId) headers['mcp-session-id'] = this.sessionId
+    if (this.initialized) headers['mcp-protocol-version'] = this.protocolVersion
+    return headers
+  }
+
+  async post(payload) {
+    let response
+    try {
+      response = await this.fetchImpl(this.url, {
+        method: 'POST',
+        headers: this.headersFor(),
+        body: JSON.stringify(payload),
+      })
+    } catch (err) {
+      throw new ServerError(`cannot reach the workspace server at ${this.url}: ${err.message}`)
+    }
+
+    const body = await response.text()
+    if (!response.ok) {
+      // Always name the status: a swallowed request otherwise looks exactly
+      // like a successful one from the caller's side.
+      throw new ServerError(
+        `workspace server returned HTTP ${response.status}${body ? `: ${truncate(body.trim(), 300)}` : ''}`,
+        { status: response.status },
+      )
+    }
+
+    const sessionId = response.headers && response.headers.get && response.headers.get('mcp-session-id')
+    if (sessionId) this.sessionId = sessionId
+
+    return parseResponseBody(body, (response.headers && response.headers.get && response.headers.get('content-type')) || '')
+  }
+
+  async request(method, params, { allowReconnect = true } = {}) {
+    const id = this.nextId
+    this.nextId += 1
+    let message
+    try {
+      message = await this.post({ jsonrpc: '2.0', id, method, params })
+    } catch (err) {
+      // The workspace server keeps its sessions alive by pinging them over the
+      // SSE GET stream, and a CLI never opens that stream — so a session can be
+      // dropped underneath a command that is merely a little slow, and a
+      // two-call command like `attachment get` is exactly long enough to hit
+      // it. Re-establishing is invisible and correct; surfacing "session not
+      // found" to somebody who never asked for a session is not.
+      if (allowReconnect && isLostSession(err)) {
+        this.sessionId = null
+        this.initialized = false
+        await this.connect()
+        return this.request(method, params, { allowReconnect: false })
+      }
+      throw err
+    }
+    if (!message) throw new ServerError(`the server sent no response to ${method}`)
+    if (message.error) {
+      const { code, message: text } = message.error
+      throw new ServerError(`${method} failed${code !== undefined ? ` (${code})` : ''}: ${text || 'unknown error'}`)
+    }
+    return message.result
+  }
+
+  /**
+   * End the session rather than letting the server hold it until it decides the
+   * client is gone. Failure here is never interesting — the command already
+   * did its work — so it is swallowed.
+   */
+  async close() {
+    if (!this.sessionId) return
+    const headers = this.headersFor()
+    this.sessionId = null
+    this.initialized = false
+    try {
+      await this.fetchImpl(this.url, { method: 'DELETE', headers })
+    } catch {
+      // Nothing to do: the session expires on its own.
+    }
+  }
+
+  async notify(method, params) {
+    await this.post({ jsonrpc: '2.0', method, params })
+  }
+
+  async connect() {
+    if (this.initialized) return
+    await this.request('initialize', {
+      protocolVersion: this.protocolVersion,
+      capabilities: {},
+      clientInfo: CLIENT_INFO,
+    })
+    this.initialized = true
+    await this.notify('notifications/initialized', {})
+  }
+
+  async listTools() {
+    await this.connect()
+    const result = await this.request('tools/list', {})
+    return (result && result.tools) || []
+  }
+
+  /**
+   * Call a tool and return its text.
+   *
+   * A tool that answers with `isError` is a refusal by the workspace (a bad
+   * status, a memory name that does not match the required shape), not a
+   * transport failure — it still becomes a non-zero exit, but with the
+   * server's own wording rather than a stack.
+   */
+  async callTool(name, args = {}) {
+    await this.connect()
+    const result = await this.request('tools/call', { name, arguments: pruneUndefined(args) })
+    const text = contentToText(result)
+    if (result && result.isError) {
+      throw new ServerError(text || `${name} failed`)
+    }
+    return { text, result }
+  }
+}
+
+/** True when an error says the server no longer knows our session. */
+export function isLostSession(err) {
+  return Boolean(err) && err.status === 404 && /session/i.test(err.message || '')
+}
+
+/** Drop keys the caller left unset so optional tool arguments stay absent. */
+export function pruneUndefined(object) {
+  const out = {}
+  for (const [key, value] of Object.entries(object || {})) {
+    if (value !== undefined && value !== null) out[key] = value
+  }
+  return out
+}

package/src/version.js

@@ -0,0 +1,13 @@
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+import { createRequire } from 'node:module'
+
+/**
+ * The CLI's version, read from its own package.json.
+ *
+ * This package rides the repository's release tags rather than carrying a
+ * version of its own, so the manifest is the single place the number appears —
+ * hard-coding it here as well is how the two drift apart by one release.
+ */
+export const VERSION = createRequire(import.meta.url)('../package.json').version