JavaScript Scripts

Dawn can run JavaScript when a task is easier to solve with code than with prose. Scripts are useful for parsing files, reshaping data, generating reports, and producing artifacts that should be attached back to the conversation.

What Scripts Are For

JavaScript scripts let a Dawn agent do deterministic local computation inside Dawn’s controlled runtime. Use them when the task needs loops, parsing, aggregation, sorting, validation, or file generation.

Good script use cases include:

• reading a CSV, JSON, markdown, or text attachment and producing a cleaned output;
• combining several file inputs into a summary table or report;
• validating structured data against simple rules;
• creating generated files such as markdown, JSON, CSV, or HTML;
• transforming screenshots, exported logs, or copied records into a more useful format.

For normal conversation, ask the agent directly. Use scripts when the work is data-shaped and should be repeatable.

How The Agent Decides To Use A Script

The user does not write the script. The agent decides when a script is the right tool for the request and runs it as part of completing the task.

Dawn ships with a built-in Skill that explains when and how scripts should be used. The agent reads it before deciding whether to write code or stay in prose, so the feature behaves predictably across the workspace without per-conversation coaching.

If your team wants to adjust the guidance (preferred output formats, naming conventions, or which kinds of jobs warrant a script), extend or replace the built-in Skill like any other workspace Skill. See Skills and the agent-assisted authoring guidance there.

How Dawn Uses Files

Scripts do not run against your development machine. They run against the files Dawn exposes to the conversation.

The script workspace can include:

• files attached to the current conversation;
• workspace files the agent is allowed to reference;
• generated files created by previous tool work;
• new files created by the script and returned as outputs.

Generated files should become durable workspace files when Dawn returns them. If a generated file is attached to a message, the attachment is a link to that durable file, not a separate hidden copy.

Working With The Script Workspace

The script runtime exposes a workspace-style file system so code can inspect available inputs and create outputs. The exact file list depends on the current thread, selected workspace, and what the agent has permission to use.

Common operations include:

• listing a directory to discover available files;
• reading file text or bytes;
• writing a new generated file;
• returning a generated file as an attachment;
• using file metadata to decide which input to process.

If a script cannot see a file you expected, check that the file was actually attached to the conversation or available as a workspace file. Mentioning a file should reference the existing file; it should not create a duplicate.

Runtime Characteristics

Scripts run in the same process as the Dawn agent. There is no virtual machine to spin up, no container to start, and no remote sandbox to wait on, so a typical script returns in well under a second. That speed is what makes scripts feel like part of the conversation rather than a separate computation step.

The tradeoff is size:

• Memory and CPU are limited.
• The runtime is built for short scripts, not multi-minute crunching.
• Validate a file, reshape a table, diff two JSON exports, walk a folder of markdown. Those are the right shape.
• A long-running computation over a very large dataset is not.

When a job needs more headroom, use a Workflow, a connected source, or a real development environment outside Dawn.

What Scripts Don’t Do

Scripts are scoped to data and file work, not general-purpose computing. They do not:

• install packages or fetch dependencies;
• run builds or execute test suites;
• access workspace secrets;
• browse the network;
• automate the browser (use the Browser Extension for that);
• operate on a host filesystem.

Scripts can only use the file and tool access Dawn grants to the agent. Sensitive files are only available when workspace policy allows the selected agent to work with them. When a task really needs a full development environment, use the Dawn CLI, the VS Code extension, a connected source, or a Workflow instead.

Returning Results

Scripts can return structured values for the agent to summarize and can create files for users to download or preview.

Use generated files when:

• the output is too large for chat;
• the result should be reused later;
• the output has a specific format such as CSV, JSON, HTML, or markdown;
• the user asked for a file to be created or transformed.

Use a chat reply when the result is short and does not need to be downloaded.

Good Prompts For Script Work

When asking Dawn to use JavaScript, describe the input files, the desired output, and the format.

Examples:

Use JavaScript to inspect the attached JSON export and return a CSV with one row per failed job.

Read the attached support tickets, group them by issue type, and create a markdown report with examples.

Create a generated JSON file containing only the active records from this CSV.

Troubleshooting

• The script cannot find a file: attach the file to the thread or mention the existing workspace file explicitly.
• A generated file cannot be downloaded: refresh the thread and check whether the output appears in the file list. If it does not, ask Dawn to recreate the file.
• The output is truncated: ask Dawn to return a file instead of pasting the full result into the message.
• The script fails on a large input: split the input or ask Dawn to process a smaller subset first.
• The script used the wrong file: refer to the exact filename or file mention in the prompt.

Use JavaScript to inspect the attached file and create a concise output file.

List the files available to this script workspace before processing anything.