Workspace

A small computer the owner’s agents share, where files stay between runs. Each agent has its own folder. Use it for spreadsheets, Office files, charts and anything that needs code.

• Files come in with open: Drive files and email attachments land in /work/inbox, Google files as .xlsx, .docx and .pptx.
• Code runs with bash, such as python report.py. It has no internet.
• Files go out through other tools: files.save puts one in Drive, and mail’s attach takes { "workspace": "<path>" }.
• /work/shared is for what you leave another agent.

Code can call your other tools, with the same checks: from roadstar import mail in Python. A call the check holds back returns not_done_yet or refused and the code carries on: ask the owner once the run is done.

Nothing here touches the owner’s own things, so these tools need no yes.

How to use it

What find_tools sends with these tools, word for word:

A small computer the owner’s agents share, where files stay between runs: Python 3 with pandas, numpy, openpyxl, XlsxWriter, python-pptx, python-docx, pypdf and matplotlib, Node and a shell, and no internet. Runs start in your own folder; /work/inbox holds files opened from Drive and mail, and /work/shared is for what you leave another agent. Edit Office files here with code. Files leave through your other tools, which take a workspace path: files.save puts one in Drive, and mail’s attach takes {workspace: path}. Code calls your other tools as group.action(...), with the same input and checks: in Python, from roadstar import mail; in JavaScript, in a script in your folder, import { mail } from "roadstar" and await each call. A call the check holds back returns {not_done_yet} or {refused} and the code carries on; ask the owner in your reply once the run is done. A refused call raises ToolError. Write scripts to files and run them, such as python report.py, and write results to files from code: the shell can’t pipe or redirect node’s or python’s output. Only a run’s output reaches you, cut to 20,000 characters, so print what you need. Formulas are saved, not worked out: Excel and Sheets do that on open. A run stops after 120 s or 300 tool calls.

Tools

Tool	What it does	Owner’s yes
workspace.bash	Run a shell command in your folder, such as python report.py: its output, exit code and the tools its code called	No
workspace.read	A text file’s lines from offset (1 is the first), 2,000 at a time; nextOffset gives the rest. A binary file, such as .xlsx, gives its size: work on it with code	No
workspace.write	Write a text file, making its folders; replaces one that’s there	No
workspace.edit	Replace exact text in a text file; oldText must appear once	No
workspace.open	Copy Drive files and email attachments into /work/inbox. Google Sheets, Docs and Slides arrive as .xlsx, .docx and .pptx. Each file’s path, and from: the Drive file it came from, for files.save’s over	No

bash

workspace.bash · Run a shell command in your folder, such as python report.py: its output, exit code and the tools its code called.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
command	text	yes	1–20,000 characters

Returns:

{
  calls: Record<string, number>;
  tookMs: number;
  usage: RunUsage;
  stopped?: string;
  exitCode: number | null;
  output: string;
}

read

workspace.read · A text file’s lines from offset (1 is the first), 2,000 at a time; nextOffset gives the rest. A binary file, such as .xlsx, gives its size: work on it with code.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
path	text	yes	1–500 characters
offset	whole number	no	1 or more
limit	whole number	no	1–2000

Returns:

{
  path: string;
  text: string;
  totalLines: number;
  nextOffset: number | null;
} | {
  path: string;
  binary: true;
  size: number;
}

write

workspace.write · Write a text file, making its folders; replaces one that’s there.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
path	text	yes	1–500 characters
content	text	yes	up to 2,000,000 characters

Returns:

{
  path: string;
  size: number;
}

edit

workspace.edit · Replace exact text in a text file; oldText must appear once.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	Limits
path	text	yes	1–500 characters
oldText	text	yes	1–200,000 characters
newText	text	yes	up to 200,000 characters

Returns:

{
  path: string;
  size: number;
}

open

workspace.open · Copy Drive files and email attachments into /work/inbox. Google Sheets, Docs and Slides arrive as .xlsx, .docx and .pptx. Each file’s path, and from: the Drive file it came from, for files.save’s over.

Owner’s yes: No. Nothing of the owner’s changes.

Input	Type	Required	What it is	Limits
files	list of text	no	Drive files: ids from search or the files tools, or links	up to 20 items, each 3–500 characters
attachments	list of { email?, attachment }	no	An attachment’s id from search; for mail not in search, the thread’s id from mail search and the id mail read listed	up to 20 items
attachments[].email	text	no		3–500 characters
attachments[].attachment	text	yes		3–300 characters

Returns:

{
  opened: Record<string, unknown>[];
}

Types

Named types in the results above.

type RunUsage = {
  cpuMs: number;
  peakBytes: number;
  tookMs: number;
  bytesWritten: number;
}