Workspace script datasets
Use the installed SKILL.md path from the skill catalog with read_skill_file({"path":"<catalog path>"}), and resolve reference paths relative to that file.
Read runtime.md before writing a script or registering its input/output contract. The Assistant needs WorkspaceScriptDataset, SandboxFile and skillsMiddleware with Sandbox enabled; live dashboards additionally need LiveDashboard.
- Inspect the actual file using
sandbox_read_file, or discover/preview the actual upstream data source. Do not create fictitious rows to satisfy a requested metric. - Create the script with
sandbox_write_file({"file_path":"scripts/sales.py","content":"..."}); JavaScript uses a.mjsfile. Read and edit existing files withsandbox_edit_file/sandbox_multi_edit_file. Use workspace-relative paths;contentis a string, not anhtmlfield. No plugin-specific file write/read tools are needed. - Implement the runtime's
query(ctx)contract from the reference. Read input only through declaredctx.files/ctx.sourcesaliases. Apply filters fromctx.parameterson every execution. There is no arbitrary network access or package installation in Dataset execution. - Register the file with
workspace_dataset_register. Declare language, files, upstream canonicalbindingJson, parameters and output fields/grain. Registration saves a governed definition; writing a.py/.mjsfile alone does not register it. - Default
mode: pinnedsnapshots the code while inputs remain live. After code edits, register the new code and update the dashboard Binding through successful previews.currentintentionally executes the latest registered file; it must be an explicit choice. - Copy returned
discoveryRequesttodashboard_discover, and returnedbindingJsonunchanged todashboard_preview_binding. Verify real rows, totals and filters. Do not translate the canonical Binding into the simplifieddashboard_previewshape. - Follow the
live-dashboardskill for HTML or standard rendering, saving and ongoing edits. The final Binding usesworkspace_script.querywhen the user requested script processing; upstream SQL/ontology previews remain inputs, not substitutes.
Script execution remains a governed Sandbox Job even though authoring uses the common SandboxFile tools. File changes, registration receipts and dashboard save receipts prove different steps; report only steps that completed.
For an explicit team-sharing request, use workspace_dataset_prepare_publication with the exact pinned Artifact/version and includeCodeAndFiles: true. Explain that this packages code and declared UTF-8 files (64 KB code, 150 KB per file, 180 KB total) into a private platform Analytics definition. The owner reviews the bytes in Settings → Analytics and chooses organization visibility. Then discover/preview workspace_script.published_query, update the same dashboard's binding, and let the human publish it. Do not bypass the private provider guard, share the Workspace folder, or claim preparation grants access. Each upstream query runs as the viewer; revoking definition visibility denies subsequent calls, including cached file reads.