@agentrq/agentrq-ws 0.7.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Contextual, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,167 @@
+# @agentrq/agentrq-ws
+
+The AgentRQ workspace client: everything an agent can do in a workspace, from a
+shell, without spending an agent's tokens to do it.
+
+```bash
+npx @agentrq/agentrq-ws@latest help
+```
+
+It reads the `.mcp.json` in the current directory — the same file the agent
+working there uses — so inside a workspace checkout there is nothing to
+configure.
+
+```bash
+cd ~/code/my-workspace
+npx @agentrq/agentrq-ws@latest workspace
+```
+
+## Why it exists
+
+An agent talks to its workspace over MCP, which is the right shape for an agent
+and the wrong shape for a person: every call is a JSON envelope, and every
+answer is tokens the agent pays for. The same eleven tools are underneath this
+CLI, but a command is a line of shell and the answer is plain text.
+
+It is also the difference between reading an attachment and *handling* one — see
+below.
+
+## Install
+
+Nothing to install: `npx @agentrq/agentrq-ws@latest <command>` fetches it on
+demand, and it has no runtime dependencies. To keep it around:
+
+```bash
+npm install -g @agentrq/agentrq-ws
+agentrq-ws help
+```
+
+Node 20.6 or newer.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `workspace` | Show the workspace title and mission |
+| `task get <taskId>` | Fetch a task, with `--conversation` for its history |
+| `task next` | Take the next not-started task — **this dequeues the queue** |
+| `task create <title>` | Create a task |
+| `task status <taskId> <status>` | Set a task's status |
+| `reply <taskId> <text>` | Send a message to a task |
+| `attachment get <id> --task <taskId>` | Download an attachment to a file |
+| `memory load [name]` | Read a workspace memory (defaults to the index) |
+| `memory save [name] --content …` | Replace a workspace memory |
+| `memory delete [name]` | Delete a workspace memory |
+| `event publish <name>` | Publish a named event |
+| `ask <taskId> <message>` | Ask the human a question and wait |
+| `tools` | List the tools this workspace server offers |
+| `call <tool> --args '{…}'` | Call any tool directly |
+
+Every command takes `--help`, and so does every family:
+
+```bash
+agentrq-ws task --help          # lists task get / next / create / status
+agentrq-ws attachment get -h    # the one command, its options and defaults
+```
+
+`task next` is a separate verb rather than a bare `task get` on purpose: it
+claims work, and a command that mutates the queue should say so in its name.
+
+## Attachments never become your problem
+
+The underlying tools speak base64 in both directions. This CLI does not.
+
+**Uploading** takes a path. The filename, media type and encoding are worked out
+for you:
+
+```bash
+agentrq-ws reply 0isnjTCkpW5 "Build is green — log attached" --attach ./run.log
+agentrq-ws task create "Review the design" --body @brief.md --attach ./mock.png
+```
+
+**Downloading** writes a file and prints where it went. With no `--out` it lands
+in the OS temp directory:
+
+```bash
+$ agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5
+/tmp/agentrq-ws-help.txt
+```
+
+`--out` takes a directory (keeping the attachment's own name) or a full path
+(renaming it):
+
+```bash
+agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5 --out ~/Downloads
+agentrq-ws attachment get 0isp9dJxr85 --task 0isnjTCkpW5 --out ./report.pdf
+```
+
+The `--task` is needed because the download tool returns bytes and no filename —
+the task is where the name lives, so the CLI reads it first and your file
+arrives called what a human called it.
+
+## Long text
+
+Anywhere prose is expected — `--body`, `--content`, `--payload`, and a reply's
+text — `@path` reads a file and `-` reads stdin:
+
+```bash
+agentrq-ws task create "Post-mortem" --body @notes.md
+git log --oneline -20 | agentrq-ws reply 0isnjTCkpW5 -
+agentrq-ws memory save release-notes.md --content @CHANGELOG.md
+```
+
+## Asking the human something
+
+```bash
+# a form
+agentrq-ws ask 0isnjTCkpW5 "Which branch should I release from?" \
+  --field branch:string:"Branch name" --field sign:boolean:"Sign the tag?"
+
+# or a link to go and do something
+agentrq-ws ask 0isnjTCkpW5 "Approve the deploy, then confirm" --url https://example.com/approve
+```
+
+Both block until the human answers or the timeout elapses (`--timeout`, one hour
+by default and at most).
+
+## Output
+
+Commands print the server's text. `--json` prints the raw result instead, for
+piping into `jq`:
+
+```bash
+agentrq-ws tools --json | jq -r '.[].name'
+```
+
+Failures print one line and exit non-zero. A stack trace means a bug in the CLI,
+not a mistake in the command.
+
+## Choosing a server
+
+The nearest `.mcp.json` at or above the working directory is used. When it
+defines several servers, name one:
+
+```bash
+agentrq-ws workspace --server agentrq-workspace
+agentrq-ws workspace --config ../other/.mcp.json
+```
+
+| Variable | Effect |
+| --- | --- |
+| `AGENTRQ_WS_URL` | Use this server URL and ignore `.mcp.json` entirely |
+| `AGENTRQ_WS_SERVER` | Which server in `.mcp.json` to use |
+
+## Development
+
+```bash
+cd cli/agentrq-ws
+npm test                  # 147 tests, no network
+npm run test:coverage
+```
+
+The tests drive the whole path — argv, config loading, the MCP handshake, SSE
+framing, files on disk — with only the socket replaced.
+
+## License
+
+Apache-2.0

package/bin/agentrq-ws.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+import { run } from '../src/cli.js'
+
+// `agentrq-ws tools | head -1` closes the pipe while we are still writing to
+// it, and an unhandled EPIPE turns an ordinary shell idiom into a stack trace
+// and a failed exit. Piping into something that stops reading is the reader's
+// decision, not an error here.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (err) => {
+    if (err && err.code === 'EPIPE') process.exit(0)
+    throw err
+  })
+}
+
+process.exitCode = await run({ argv: process.argv.slice(2) })

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@agentrq/agentrq-ws",
+  "version": "0.7.0",
+  "description": "AgentRQ workspace client \u2014 drive an AgentRQ workspace from the command line, using the workspace's own .mcp.json",
+  "keywords": [
+    "agentrq",
+    "workspace",
+    "mcp",
+    "cli",
+    "tasks"
+  ],
+  "homepage": "https://github.com/agentrq/agentrq/tree/main/cli/agentrq-ws",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentrq/agentrq.git",
+    "directory": "cli/agentrq-ws"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "agentrq-ws": "bin/agentrq-ws.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=test/** test/*.test.js",
+    "test:ci": "node --test --experimental-test-coverage --test-coverage-exclude=test/** --test-coverage-lines=100 --test-coverage-functions=100 --test-coverage-branches=95 test/*.test.js"
+  }
+}

package/src/attachments.js

@@ -0,0 +1,152 @@
+// Copyright 2026 Contextual, Inc. https://agentrq.com
+// This notice may not be modified or removed.
+
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, dirname, extname, isAbsolute, join, resolve } from 'node:path'
+
+import { UserError } from './errors.js'
+
+/**
+ * Extension → media type. Deliberately a short table of what actually gets
+ * attached to a task rather than a dependency: anything unlisted travels as
+ * application/octet-stream, which is correct, just unspecific.
+ */
+export const MIME_TYPES = {
+  '.bmp': 'image/bmp',
+  '.csv': 'text/csv',
+  '.gif': 'image/gif',
+  '.gz': 'application/gzip',
+  '.htm': 'text/html',
+  '.html': 'text/html',
+  '.ics': 'text/calendar',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+  '.log': 'text/plain',
+  '.md': 'text/markdown',
+  '.mp3': 'audio/mpeg',
+  '.mp4': 'video/mp4',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.tar': 'application/x-tar',
+  '.txt': 'text/plain',
+  '.wav': 'audio/wav',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+  '.xml': 'application/xml',
+  '.yaml': 'application/yaml',
+  '.yml': 'application/yaml',
+  '.zip': 'application/zip',
+}
+
+export function mimeTypeFor(filename) {
+  return MIME_TYPES[extname(String(filename)).toLowerCase()] || 'application/octet-stream'
+}
+
+/**
+ * Turn a path on disk into the attachment shape the workspace tools expect.
+ *
+ * This is the whole point of the `--attach` flag: the wire format wants
+ * `{id, filename, mimeType, data}` with base64 in `data`, and nobody should
+ * have to produce that by hand. The `id` is a placeholder — the backend mints
+ * the real one and blanks `data` as it stores the bytes — but the field is part
+ * of the schema, so it is sent.
+ */
+export function readAttachment(filePath, { readFile = readFileSync, stat = statSync } = {}) {
+  const path = resolve(filePath)
+  let info
+  try {
+    info = stat(path)
+  } catch {
+    throw new UserError(`cannot attach ${filePath}: no such file`)
+  }
+  if (info.isDirectory()) {
+    throw new UserError(`cannot attach ${filePath}: it is a directory`)
+  }
+  let bytes
+  try {
+    bytes = readFile(path)
+  } catch (err) {
+    throw new UserError(`cannot read ${filePath}: ${err.message}`)
+  }
+  const filename = basename(path)
+  return {
+    id: `upload-${filename}`,
+    filename,
+    mimeType: mimeTypeFor(filename),
+    data: Buffer.from(bytes).toString('base64'),
+  }
+}
+
+/**
+ * Index the attachments mentioned in a task's text, id → {filename, mimeType}.
+ *
+ * `downloadAttachment` answers with base64 and nothing else — no name, no type
+ * — so the only way to save a file under the name a human gave it is to read
+ * the task first. Task-level attachments arrive as `- id=… name=… type=…`
+ * lines and message-level ones inside the conversation JSON, so both shapes are
+ * scanned.
+ */
+export function indexAttachments(taskText) {
+  const index = new Map()
+  const text = String(taskText || '')
+
+  const linePattern = /^\s*-\s*id=(\S+)\s+name=(.*?)\s+type=(\S+)\s*$/gm
+  for (const match of text.matchAll(linePattern)) {
+    index.set(match[1], { filename: match[2], mimeType: match[3] })
+  }
+
+  const jsonPattern = /"id"\s*:\s*"([^"]+)"\s*,\s*"filename"\s*:\s*"([^"]*)"\s*,\s*"mimeType"\s*:\s*"([^"]*)"/g
+  for (const match of text.matchAll(jsonPattern)) {
+    if (!index.has(match[1])) {
+      index.set(match[1], { filename: match[2], mimeType: match[3] })
+    }
+  }
+  return index
+}
+
+/**
+ * Work out where a downloaded attachment should land.
+ *
+ * With no `--out` it goes to the OS temp directory, which is what makes
+ * `attachment get` safe to run without thinking about the current directory.
+ * An `--out` naming an existing directory (or ending in a separator) keeps the
+ * attachment's own filename; anything else is taken as the full path to write,
+ * so `--out ./report.pdf` renames.
+ */
+export function resolveOutputPath(filename, out, { cwd = process.cwd(), temp = tmpdir(), stat = statSync } = {}) {
+  const safeName = basename(String(filename || '')) || 'attachment'
+  if (!out) return join(temp, safeName)
+
+  const endsWithSeparator = /[\\/]$/.test(out)
+  const target = isAbsolute(out) ? out : resolve(cwd, out)
+  if (endsWithSeparator || isDirectory(target, stat)) {
+    return join(target, safeName)
+  }
+  return target
+}
+
+/** True only when the path exists *and* is a directory — an existing file at
+ * `--out` is a rename target to overwrite, not somewhere to nest inside. */
+function isDirectory(path, stat) {
+  try {
+    return stat(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+/** Write base64 content to `path`, creating the directory if it is missing. */
+export function writeAttachment(path, base64, { write = writeFileSync, mkdir = mkdirSync } = {}) {
+  const buffer = Buffer.from(String(base64 || '').trim(), 'base64')
+  try {
+    mkdir(dirname(path), { recursive: true })
+    write(path, buffer)
+  } catch (err) {
+    throw new UserError(`cannot write ${path}: ${err.message}`)
+  }
+  return { path, bytes: buffer.length }
+}