@loopstack/filesystem-examples 0.1.1

package/README.md

@@ -0,0 +1,92 @@
+---
+title: Filesystem Examples
+description: Workflow examples for filesystem operations in Loopstack — Docker sandbox, remote file browsing, remote command execution, local file tree.
+---
+
+# @loopstack/filesystem-examples
+
+> Filesystem workflow examples for the [Loopstack](https://loopstack.ai) automation framework.
+
+Four ways workflows interact with the filesystem in Loopstack: isolated Docker sandboxes, remote workspace browsing, remote command execution, and local file-tree inspection.
+
+## Install as Source (Recommended)
+
+```bash
+npx giget@latest gh:loopstack-ai/loopstack/registry/examples/filesystem-examples src/filesystem-examples
+```
+
+Register the module:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { LoopstackModule } from '@loopstack/loopstack-module';
+import { FilesystemExamplesModule } from './filesystem-examples/filesystem-examples.module';
+
+@Module({
+  imports: [LoopstackModule.forRoot(), FilesystemExamplesModule],
+})
+export class AppModule {}
+```
+
+## Install as a Dependency
+
+```bash
+npm install @loopstack/filesystem-examples
+```
+
+```typescript
+import { FilesystemExamplesModule } from '@loopstack/filesystem-examples';
+```
+
+## Environment
+
+The sandbox example requires Docker. The remote examples require a running remote server (`SANDBOX_URL`, `SANDBOX_AGENT_URL`) — see `@loopstack/remote-client`'s `forRoot` config.
+
+## Examples
+
+| Example                                       | Studio title                                | Description                                                                  |
+| --------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------------------- |
+| [Sandbox](#sandbox)                           | `Filesystem - Sandbox Example`              | Full Docker sandbox lifecycle — init, file ops, destroy                      |
+| [Remote File Explorer](#remote-file-explorer) | `Filesystem - Remote File Explorer Example` | Browse a remote workspace via `GlobTool` + `ReadTool`                        |
+| [Remote Client](#remote-client)               | `Filesystem - Remote Client Example`        | Run commands and edit files on a remote machine via `BashTool` + `WriteTool` |
+| [Local File Explorer](#local-file-explorer)   | `Filesystem - Local File Explorer Example`  | Build a workspace file tree with `FileSystemService`                         |
+
+---
+
+## Sandbox
+
+Walks the complete Docker sandbox lifecycle: `sandboxInit` → directory + file operations (`sandboxCreateDirectory`, `sandboxWriteFile`, `sandboxReadFile`, `sandboxListDirectory`, `sandboxExists`, `sandboxFileInfo`, `sandboxDelete`) → `sandboxDestroy`. Useful for isolated execution of untrusted code.
+
+### Files
+
+- `sandbox-example.workflow.ts` — workflow class
+
+## Remote File Explorer
+
+Uses `GlobTool` and `ReadTool` from `@loopstack/remote-client` to find Markdown files in a remote workspace and read the first match.
+
+### Files
+
+- `remote-file-explorer-example.workflow.ts` — workflow class
+
+## Remote Client
+
+Demonstrates `@loopstack/remote-client` beyond file browsing: write a file via `WriteTool`, run a shell command via `BashTool`, then read the result with `ReadTool`. Useful when you need command execution against a remote workspace.
+
+### Files
+
+- `remote-client-example.workflow.ts` — workflow class
+
+## Local File Explorer
+
+Demonstrates `FileSystemService` from `@loopstack/local-file-explorer-module` — builds a file tree of the workspace root and renders it as markdown. The same module also exposes a REST API for the Studio file panel.
+
+### Files
+
+- `local-file-explorer-example.workflow.ts` — workflow class
+
+## About
+
+Author: [Jakob Klippel](https://www.linkedin.com/in/jakob-klippel/)
+
+License: MIT

package/dist/filesystem-examples.module.d.ts

@@ -0,0 +1,3 @@
+export declare class FilesystemExamplesModule {
+}
+//# sourceMappingURL=filesystem-examples.module.d.ts.map

package/dist/filesystem-examples.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-examples.module.d.ts","sourceRoot":"","sources":["../src/filesystem-examples.module.ts"],"names":[],"mappings":"AAmBA,qBAea,wBAAwB;CAAG"}

package/dist/filesystem-examples.module.js

@@ -0,0 +1,47 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesystemExamplesModule = void 0;
+const common_1 = require("@nestjs/common");
+const common_2 = require("@loopstack/common");
+const local_file_explorer_module_1 = require("@loopstack/local-file-explorer-module");
+const remote_client_1 = require("@loopstack/remote-client");
+const remote_file_explorer_module_1 = require("@loopstack/remote-file-explorer-module");
+const sandbox_filesystem_1 = require("@loopstack/sandbox-filesystem");
+const sandbox_tool_1 = require("@loopstack/sandbox-tool");
+const local_file_explorer_example_workflow_1 = require("./workflows/local-file-explorer/local-file-explorer-example.workflow");
+const remote_client_example_workflow_1 = require("./workflows/remote-client/remote-client-example.workflow");
+const remote_file_explorer_example_workflow_1 = require("./workflows/remote-file-explorer/remote-file-explorer-example.workflow");
+const sandbox_example_workflow_1 = require("./workflows/sandbox/sandbox-example.workflow");
+const WORKFLOWS = [
+    sandbox_example_workflow_1.SandboxExampleWorkflow,
+    remote_file_explorer_example_workflow_1.RemoteFileExplorerExampleWorkflow,
+    remote_client_example_workflow_1.RemoteClientExampleWorkflow,
+    local_file_explorer_example_workflow_1.LocalFileExplorerExampleWorkflow,
+];
+let FilesystemExamplesModule = class FilesystemExamplesModule {
+};
+exports.FilesystemExamplesModule = FilesystemExamplesModule;
+exports.FilesystemExamplesModule = FilesystemExamplesModule = __decorate([
+    (0, common_2.StudioApp)({
+        title: 'Filesystem Examples',
+        workflows: WORKFLOWS,
+    }),
+    (0, common_1.Module)({
+        imports: [
+            sandbox_filesystem_1.SandboxFilesystemModule,
+            sandbox_tool_1.SandboxToolModule,
+            remote_file_explorer_module_1.RemoteFileExplorerModule.forFeature(),
+            remote_client_1.RemoteClientModule.forFeature({ slots: [{ id: 'sandbox', type: 'sandbox', title: 'Sandbox' }] }),
+            local_file_explorer_module_1.LocalFileExplorerModule.forFeature(),
+        ],
+        providers: WORKFLOWS,
+        exports: WORKFLOWS,
+    })
+], FilesystemExamplesModule);
+//# sourceMappingURL=filesystem-examples.module.js.map

package/dist/filesystem-examples.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-examples.module.js","sourceRoot":"","sources":["../src/filesystem-examples.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,8CAA8C;AAC9C,sFAAgF;AAChF,4DAA8D;AAC9D,wFAAkF;AAClF,sEAAwE;AACxE,0DAA4D;AAC5D,+HAAwH;AACxH,6GAAuG;AACvG,kIAA2H;AAC3H,2FAAsF;AAEtF,MAAM,SAAS,GAAG;IAChB,iDAAsB;IACtB,yEAAiC;IACjC,4DAA2B;IAC3B,uEAAgC;CACjC,CAAC;AAiBK,IAAM,wBAAwB,GAA9B,MAAM,wBAAwB;CAAG,CAAA;AAA3B,4DAAwB;mCAAxB,wBAAwB;IAfpC,IAAA,kBAAS,EAAC;QACT,KAAK,EAAE,qBAAqB;QAC5B,SAAS,EAAE,SAAS;KACrB,CAAC;IACD,IAAA,eAAM,EAAC;QACN,OAAO,EAAE;YACP,4CAAuB;YACvB,gCAAiB;YACjB,sDAAwB,CAAC,UAAU,EAAE;YACrC,kCAAkB,CAAC,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;YAChG,oDAAuB,CAAC,UAAU,EAAE;SACrC;QACD,SAAS,EAAE,SAAS;QACpB,OAAO,EAAE,SAAS;KACnB,CAAC;GACW,wBAAwB,CAAG"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './filesystem-examples.module';
+export * from './workflows/sandbox/sandbox-example.workflow';
+export * from './workflows/remote-file-explorer/remote-file-explorer-example.workflow';
+export * from './workflows/remote-client/remote-client-example.workflow';
+export * from './workflows/local-file-explorer/local-file-explorer-example.workflow';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8CAA8C,CAAC;AAC7D,cAAc,wEAAwE,CAAC;AACvF,cAAc,0DAA0D,CAAC;AACzE,cAAc,sEAAsE,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./filesystem-examples.module"), exports);
+__exportStar(require("./workflows/sandbox/sandbox-example.workflow"), exports);
+__exportStar(require("./workflows/remote-file-explorer/remote-file-explorer-example.workflow"), exports);
+__exportStar(require("./workflows/remote-client/remote-client-example.workflow"), exports);
+__exportStar(require("./workflows/local-file-explorer/local-file-explorer-example.workflow"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+DAA6C;AAC7C,+EAA6D;AAC7D,yGAAuF;AACvF,2FAAyE;AACzE,uGAAqF"}

package/dist/workflows/local-file-explorer/local-file-explorer-example.workflow.d.ts

@@ -0,0 +1,12 @@
+import { BaseWorkflow } from '@loopstack/common';
+import { FileSystemService } from '@loopstack/local-file-explorer-module';
+interface LocalFileExplorerState {
+    fileCount?: number;
+}
+export declare class LocalFileExplorerExampleWorkflow extends BaseWorkflow {
+    private readonly fileSystem;
+    constructor(fileSystem: FileSystemService);
+    listTree(_state: LocalFileExplorerState): Promise<void>;
+}
+export {};
+//# sourceMappingURL=local-file-explorer-example.workflow.d.ts.map

package/dist/workflows/local-file-explorer/local-file-explorer-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-explorer-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/local-file-explorer/local-file-explorer-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAA0C,MAAM,mBAAmB,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAE1E,UAAU,sBAAsB;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAKa,gCAAiC,SAAQ,YAAY;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,iBAAiB;IAKpD,QAAQ,CAAC,MAAM,EAAE,sBAAsB;CAe9C"}

package/dist/workflows/local-file-explorer/local-file-explorer-example.workflow.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalFileExplorerExampleWorkflow = void 0;
+const common_1 = require("@loopstack/common");
+const local_file_explorer_module_1 = require("@loopstack/local-file-explorer-module");
+let LocalFileExplorerExampleWorkflow = class LocalFileExplorerExampleWorkflow extends common_1.BaseWorkflow {
+    fileSystem;
+    constructor(fileSystem) {
+        super();
+        this.fileSystem = fileSystem;
+    }
+    async listTree(_state) {
+        const tree = await this.fileSystem.buildFileTree(process.cwd());
+        const lines = tree.slice(0, 50).map((node) => `- ${node.path} (${node.type})`);
+        await this.documentStore.save(common_1.MarkdownDocument, {
+            markdown: [
+                `# Workspace File Tree`,
+                '',
+                `Found ${tree.length} top-level entries in \`${process.cwd()}\`.`,
+                '',
+                ...lines,
+                tree.length > 50 ? `\n_(${tree.length - 50} more entries omitted)_` : '',
+            ].join('\n'),
+        });
+    }
+};
+exports.LocalFileExplorerExampleWorkflow = LocalFileExplorerExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], LocalFileExplorerExampleWorkflow.prototype, "listTree", null);
+exports.LocalFileExplorerExampleWorkflow = LocalFileExplorerExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Filesystem - Local File Explorer Example',
+        description: 'Demonstrates @loopstack/local-file-explorer-module — uses FileSystemService to build a file tree of the workspace root and render it as markdown. The module also exposes a REST API for the Studio file panel.',
+    }),
+    __metadata("design:paramtypes", [local_file_explorer_module_1.FileSystemService])
+], LocalFileExplorerExampleWorkflow);
+//# sourceMappingURL=local-file-explorer-example.workflow.js.map

package/dist/workflows/local-file-explorer/local-file-explorer-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-file-explorer-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/local-file-explorer/local-file-explorer-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAyF;AACzF,sFAA0E;AAWnE,IAAM,gCAAgC,GAAtC,MAAM,gCAAiC,SAAQ,qBAAY;IACnC;IAA7B,YAA6B,UAA6B;QACxD,KAAK,EAAE,CAAC;QADmB,eAAU,GAAV,UAAU,CAAmB;IAE1D,CAAC;IAGK,AAAN,KAAK,CAAC,QAAQ,CAAC,MAA8B;QAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QAChE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC;QAE/E,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,yBAAgB,EAAE;YAC9C,QAAQ,EAAE;gBACR,uBAAuB;gBACvB,EAAE;gBACF,SAAS,IAAI,CAAC,MAAM,2BAA2B,OAAO,CAAC,GAAG,EAAE,KAAK;gBACjE,EAAE;gBACF,GAAG,KAAK;gBACR,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,MAAM,GAAG,EAAE,yBAAyB,CAAC,CAAC,CAAC,EAAE;aACzE,CAAC,IAAI,CAAC,IAAI,CAAC;SACb,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AArBY,4EAAgC;AAMrC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;gEAezB;2CApBU,gCAAgC;IAL5C,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,0CAA0C;QACjD,WAAW,EACT,iNAAiN;KACpN,CAAC;qCAEyC,8CAAiB;GAD/C,gCAAgC,CAqB5C"}

package/dist/workflows/remote-client/remote-client-example.workflow.d.ts

@@ -0,0 +1,16 @@
+import { BaseWorkflow } from '@loopstack/common';
+import { BashTool, ReadTool, WriteTool } from '@loopstack/remote-client';
+interface RemoteClientState {
+    filePath?: string;
+}
+export declare class RemoteClientExampleWorkflow extends BaseWorkflow {
+    private readonly bash;
+    private readonly read;
+    private readonly write;
+    constructor(bash: BashTool, read: ReadTool, write: WriteTool);
+    writeFile(_state: RemoteClientState): Promise<void>;
+    runCommand(state: RemoteClientState): Promise<void>;
+    readBack(state: RemoteClientState): Promise<void>;
+}
+export {};
+//# sourceMappingURL=remote-client-example.workflow.d.ts.map

package/dist/workflows/remote-client/remote-client-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-client-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/remote-client/remote-client-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEzE,UAAU,iBAAiB;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAKa,2BAA4B,SAAQ,YAAY;IAEzD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAFL,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,SAAS;IAM7B,SAAS,CAAC,MAAM,EAAE,iBAAiB;IAcnC,UAAU,CAAC,KAAK,EAAE,iBAAiB;IAYnC,QAAQ,CAAC,KAAK,EAAE,iBAAiB;CAQxC"}

package/dist/workflows/remote-client/remote-client-example.workflow.js

@@ -0,0 +1,84 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteClientExampleWorkflow = void 0;
+const common_1 = require("@loopstack/common");
+const remote_client_1 = require("@loopstack/remote-client");
+let RemoteClientExampleWorkflow = class RemoteClientExampleWorkflow extends common_1.BaseWorkflow {
+    bash;
+    read;
+    write;
+    constructor(bash, read, write) {
+        super();
+        this.bash = bash;
+        this.read = read;
+        this.write = write;
+    }
+    async writeFile(_state) {
+        const filePath = '/tmp/remote-client-example.txt';
+        await this.write.call({
+            file_path: filePath,
+            content: 'Hello from RemoteClientExampleWorkflow!\n',
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Wrote file ${filePath}.`,
+        });
+        this.assignState({ filePath });
+    }
+    async runCommand(state) {
+        const result = await this.bash.call({
+            command: `wc -l ${state.filePath} && date`,
+        });
+        const stdout = result.data?.stdout ?? '';
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Command output:\n\`\`\`\n${stdout}\n\`\`\``,
+        });
+    }
+    async readBack(state) {
+        const result = await this.read.call({ file_path: state.filePath });
+        const content = result.data?.content ?? '';
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Final file content:\n\`\`\`\n${content}\n\`\`\``,
+        });
+    }
+};
+exports.RemoteClientExampleWorkflow = RemoteClientExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'file_written' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RemoteClientExampleWorkflow.prototype, "writeFile", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'file_written', to: 'command_executed' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RemoteClientExampleWorkflow.prototype, "runCommand", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'command_executed', to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RemoteClientExampleWorkflow.prototype, "readBack", null);
+exports.RemoteClientExampleWorkflow = RemoteClientExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Filesystem - Remote Client Example',
+        description: 'Demonstrates @loopstack/remote-client tools beyond file browsing: write a file, run a shell command on the remote machine via BashTool, read the result. Useful when you need command execution against a remote workspace.',
+    }),
+    __metadata("design:paramtypes", [remote_client_1.BashTool,
+        remote_client_1.ReadTool,
+        remote_client_1.WriteTool])
+], RemoteClientExampleWorkflow);
+//# sourceMappingURL=remote-client-example.workflow.js.map

package/dist/workflows/remote-client/remote-client-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-client-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/remote-client/remote-client-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AACxF,4DAAyE;AAWlE,IAAM,2BAA2B,GAAjC,MAAM,2BAA4B,SAAQ,qBAAY;IAExC;IACA;IACA;IAHnB,YACmB,IAAc,EACd,IAAc,EACd,KAAgB;QAEjC,KAAK,EAAE,CAAC;QAJS,SAAI,GAAJ,IAAI,CAAU;QACd,SAAI,GAAJ,IAAI,CAAU;QACd,UAAK,GAAL,KAAK,CAAW;IAGnC,CAAC;IAGK,AAAN,KAAK,CAAC,SAAS,CAAC,MAAyB;QACvC,MAAM,QAAQ,GAAG,gCAAgC,CAAC;QAClD,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YACpB,SAAS,EAAE,QAAQ;YACnB,OAAO,EAAE,2CAA2C;SACrD,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,cAAc,QAAQ,GAAG;SAChC,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACjC,CAAC;IAGK,AAAN,KAAK,CAAC,UAAU,CAAC,KAAwB;QACvC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YAClC,OAAO,EAAE,SAAS,KAAK,CAAC,QAAQ,UAAU;SAC3C,CAAC,CAAC;QACH,MAAM,MAAM,GAAI,MAAM,CAAC,IAA4B,EAAE,MAAM,IAAI,EAAE,CAAC;QAClE,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,4BAA4B,MAAM,UAAU;SACnD,CAAC,CAAC;IACL,CAAC;IAGK,AAAN,KAAK,CAAC,QAAQ,CAAC,KAAwB;QACrC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,QAAS,EAAE,CAAC,CAAC;QACpE,MAAM,OAAO,GAAI,MAAM,CAAC,IAA6B,EAAE,OAAO,IAAI,EAAE,CAAC;QACrE,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,gCAAgC,OAAO,UAAU;SACxD,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AA5CY,kEAA2B;AAUhC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;;;;4DAYlC;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,kBAAkB,EAAE,CAAC;;;;6DAU5D;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;2DAQnD;sCA3CU,2BAA2B;IALvC,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EACT,6NAA6N;KAChO,CAAC;qCAGyB,wBAAQ;QACR,wBAAQ;QACP,yBAAS;GAJxB,2BAA2B,CA4CvC"}

package/dist/workflows/remote-file-explorer/remote-file-explorer-example.workflow.d.ts

@@ -0,0 +1,14 @@
+import { BaseWorkflow } from '@loopstack/common';
+import { GlobTool, ReadTool } from '@loopstack/remote-client';
+interface RemoteFileExplorerState {
+    firstMatch?: string;
+}
+export declare class RemoteFileExplorerExampleWorkflow extends BaseWorkflow {
+    private readonly glob;
+    private readonly read;
+    constructor(glob: GlobTool, read: ReadTool);
+    listFiles(_state: RemoteFileExplorerState): Promise<void>;
+    readFirst(state: RemoteFileExplorerState): Promise<void>;
+}
+export {};
+//# sourceMappingURL=remote-file-explorer-example.workflow.d.ts.map

package/dist/workflows/remote-file-explorer/remote-file-explorer-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file-explorer-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/remote-file-explorer/remote-file-explorer-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAE9D,UAAU,uBAAuB;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAKa,iCAAkC,SAAQ,YAAY;IAE/D,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,QAAQ;IAM3B,SAAS,CAAC,MAAM,EAAE,uBAAuB;IAezC,SAAS,CAAC,KAAK,EAAE,uBAAuB;CAiB/C"}

package/dist/workflows/remote-file-explorer/remote-file-explorer-example.workflow.js

@@ -0,0 +1,72 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteFileExplorerExampleWorkflow = void 0;
+const common_1 = require("@loopstack/common");
+const remote_client_1 = require("@loopstack/remote-client");
+let RemoteFileExplorerExampleWorkflow = class RemoteFileExplorerExampleWorkflow extends common_1.BaseWorkflow {
+    glob;
+    read;
+    constructor(glob, read) {
+        super();
+        this.glob = glob;
+        this.read = read;
+    }
+    async listFiles(_state) {
+        const result = await this.glob.call({ pattern: '**/*.md' });
+        const files = result.data?.files ?? [];
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Found ${files.length} markdown files:\n${files
+                .slice(0, 20)
+                .map((f) => `- ${f}`)
+                .join('\n')}`,
+        });
+        this.assignState({ firstMatch: files[0] });
+    }
+    async readFirst(state) {
+        if (!state.firstMatch) {
+            await this.documentStore.save(common_1.MessageDocument, {
+                role: 'assistant',
+                text: 'No markdown files to read.',
+            });
+            return;
+        }
+        const result = await this.read.call({ file_path: state.firstMatch });
+        const content = result.data?.content ?? '';
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `# ${state.firstMatch}\n\n${content.slice(0, 500)}`,
+        });
+    }
+};
+exports.RemoteFileExplorerExampleWorkflow = RemoteFileExplorerExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'listed' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RemoteFileExplorerExampleWorkflow.prototype, "listFiles", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'listed', to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RemoteFileExplorerExampleWorkflow.prototype, "readFirst", null);
+exports.RemoteFileExplorerExampleWorkflow = RemoteFileExplorerExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Filesystem - Remote File Explorer Example',
+        description: 'Browses a remote workspace via @loopstack/remote-client GlobTool + ReadTool — finds Markdown files, reads the first match.',
+    }),
+    __metadata("design:paramtypes", [remote_client_1.GlobTool,
+        remote_client_1.ReadTool])
+], RemoteFileExplorerExampleWorkflow);
+//# sourceMappingURL=remote-file-explorer-example.workflow.js.map

package/dist/workflows/remote-file-explorer/remote-file-explorer-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-file-explorer-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/remote-file-explorer/remote-file-explorer-example.workflow.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,8CAAwF;AACxF,4DAA8D;AAWvD,IAAM,iCAAiC,GAAvC,MAAM,iCAAkC,SAAQ,qBAAY;IAE9C;IACA;IAFnB,YACmB,IAAc,EACd,IAAc;QAE/B,KAAK,EAAE,CAAC;QAHS,SAAI,GAAJ,IAAI,CAAU;QACd,SAAI,GAAJ,IAAI,CAAU;IAGjC,CAAC;IAGK,AAAN,KAAK,CAAC,SAAS,CAAC,MAA+B;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAI,MAAM,CAAC,IAA6B,EAAE,KAAK,IAAI,EAAE,CAAC;QAEjE,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,SAAS,KAAK,CAAC,MAAM,qBAAqB,KAAK;iBAClD,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;iBACZ,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;iBACpB,IAAI,CAAC,IAAI,CAAC,EAAE;SAChB,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;IAGK,AAAN,KAAK,CAAC,SAAS,CAAC,KAA8B;QAC5C,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YACtB,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;gBAC7C,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,4BAA4B;aACnC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;QACrE,MAAM,OAAO,GAAI,MAAM,CAAC,IAA6B,EAAE,OAAO,IAAI,EAAE,CAAC;QAErE,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,wBAAe,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK,KAAK,CAAC,UAAU,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE;SAC1D,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAzCY,8EAAiC;AAStC;IADL,IAAA,mBAAU,EAAC,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC;;;;kEAa5B;AAGK;IADL,IAAA,mBAAU,EAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;;;;kEAiBzC;4CAxCU,iCAAiC;IAL7C,IAAA,iBAAQ,EAAC;QACR,KAAK,EAAE,2CAA2C;QAClD,WAAW,EACT,4HAA4H;KAC/H,CAAC;qCAGyB,wBAAQ;QACR,wBAAQ;GAHtB,iCAAiC,CAyC7C"}

package/dist/workflows/sandbox/sandbox-example.workflow.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { BaseWorkflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import { SandboxCreateDirectory, SandboxDelete, SandboxExists, SandboxFileInfo, SandboxListDirectory, SandboxReadFile, SandboxWriteFile } from '@loopstack/sandbox-filesystem';
+import { SandboxDestroy, SandboxInit } from '@loopstack/sandbox-tool';
+interface FileEntry {
+    name: string;
+    type: string;
+    size: number;
+    path: string;
+}
+interface SandboxExampleState {
+    containerId?: string;
+    fileContent?: string;
+    fileList?: FileEntry[];
+}
+declare const SandboxExampleArgsSchema: z.ZodObject<{
+    outputDir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+type SandboxExampleArgs = z.infer<typeof SandboxExampleArgsSchema>;
+export declare class SandboxExampleWorkflow extends BaseWorkflow<SandboxExampleArgs> {
+    private readonly sandboxInit;
+    private readonly sandboxDestroy;
+    private readonly sandboxWriteFile;
+    private readonly sandboxReadFile;
+    private readonly sandboxListDirectory;
+    private readonly sandboxCreateDirectory;
+    private readonly sandboxDelete;
+    private readonly sandboxExists;
+    private readonly sandboxFileInfo;
+    constructor(sandboxInit: SandboxInit, sandboxDestroy: SandboxDestroy, sandboxWriteFile: SandboxWriteFile, sandboxReadFile: SandboxReadFile, sandboxListDirectory: SandboxListDirectory, sandboxCreateDirectory: SandboxCreateDirectory, sandboxDelete: SandboxDelete, sandboxExists: SandboxExists, sandboxFileInfo: SandboxFileInfo);
+    initSandbox(state: SandboxExampleState, ctx: RunContext<SandboxExampleArgs>): Promise<void>;
+    createDir(state: SandboxExampleState): Promise<void>;
+    writeFile(state: SandboxExampleState): Promise<void>;
+    readFile(state: SandboxExampleState): Promise<void>;
+    listDir(state: SandboxExampleState): Promise<void>;
+    checkExists(state: SandboxExampleState): Promise<void>;
+    getInfo(state: SandboxExampleState): Promise<void>;
+    deleteFile(state: SandboxExampleState): Promise<void>;
+    destroySandbox(state: SandboxExampleState): Promise<void>;
+    private formatEntries;
+}
+export {};
+//# sourceMappingURL=sandbox-example.workflow.d.ts.map

package/dist/workflows/sandbox/sandbox-example.workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-example.workflow.d.ts","sourceRoot":"","sources":["../../../src/workflows/sandbox/sandbox-example.workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,YAAY,EAAyC,MAAM,mBAAmB,CAAC;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtE,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,mBAAmB;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;CACxB;AAED,QAAA,MAAM,wBAAwB;;iBAE5B,CAAC;AAEH,KAAK,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEnE,qBAMa,sBAAuB,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IAGxE,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,cAAc;IAE/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IACrC,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe;gBATf,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,cAAc,EAE9B,gBAAgB,EAAE,gBAAgB,EAClC,eAAe,EAAE,eAAe,EAChC,oBAAoB,EAAE,oBAAoB,EAC1C,sBAAsB,EAAE,sBAAsB,EAC9C,aAAa,EAAE,aAAa,EAC5B,aAAa,EAAE,aAAa,EAC5B,eAAe,EAAE,eAAe;IAM7C,WAAW,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,EAAE,UAAU,CAAC,kBAAkB,CAAC;IAiB3E,SAAS,CAAC,KAAK,EAAE,mBAAmB;IAcpC,SAAS,CAAC,KAAK,EAAE,mBAAmB;IAgBpC,QAAQ,CAAC,KAAK,EAAE,mBAAmB;IAenC,OAAO,CAAC,KAAK,EAAE,mBAAmB;IAelC,WAAW,CAAC,KAAK,EAAE,mBAAmB;IAatC,OAAO,CAAC,KAAK,EAAE,mBAAmB;IAalC,UAAU,CAAC,KAAK,EAAE,mBAAmB;IAerC,cAAc,CAAC,KAAK,EAAE,mBAAmB;IAY/C,OAAO,CAAC,aAAa;CAMtB"}

package/dist/workflows/sandbox/sandbox-example.workflow.js

@@ -0,0 +1,224 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxExampleWorkflow = void 0;
+const zod_1 = require("zod");
+const common_1 = require("@loopstack/common");
+const sandbox_filesystem_1 = require("@loopstack/sandbox-filesystem");
+const sandbox_tool_1 = require("@loopstack/sandbox-tool");
+const SandboxExampleArgsSchema = zod_1.z.object({
+    outputDir: zod_1.z.string().default(process.cwd() + '/out'),
+});
+let SandboxExampleWorkflow = class SandboxExampleWorkflow extends common_1.BaseWorkflow {
+    sandboxInit;
+    sandboxDestroy;
+    sandboxWriteFile;
+    sandboxReadFile;
+    sandboxListDirectory;
+    sandboxCreateDirectory;
+    sandboxDelete;
+    sandboxExists;
+    sandboxFileInfo;
+    constructor(sandboxInit, sandboxDestroy, sandboxWriteFile, sandboxReadFile, sandboxListDirectory, sandboxCreateDirectory, sandboxDelete, sandboxExists, sandboxFileInfo) {
+        super();
+        this.sandboxInit = sandboxInit;
+        this.sandboxDestroy = sandboxDestroy;
+        this.sandboxWriteFile = sandboxWriteFile;
+        this.sandboxReadFile = sandboxReadFile;
+        this.sandboxListDirectory = sandboxListDirectory;
+        this.sandboxCreateDirectory = sandboxCreateDirectory;
+        this.sandboxDelete = sandboxDelete;
+        this.sandboxExists = sandboxExists;
+        this.sandboxFileInfo = sandboxFileInfo;
+    }
+    async initSandbox(state, ctx) {
+        const initResult = await this.sandboxInit.call({
+            containerId: 'my-sandbox',
+            imageName: 'node:18',
+            containerName: 'my-filesystem-sandbox',
+            projectOutPath: ctx.args.outputDir,
+            rootPath: 'workspace',
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Sandbox initialized successfully. Container ID: ${initResult.data.containerId}, Docker ID: ${initResult.data.dockerId}`,
+        });
+        this.assignState({ containerId: initResult.data.containerId });
+    }
+    async createDir(state) {
+        const mkdirResult = await this.sandboxCreateDirectory.call({
+            containerId: state.containerId,
+            path: '/workspace',
+            recursive: true,
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Directory created: ${mkdirResult.data.path} (created: ${mkdirResult.data.created})`,
+        });
+    }
+    async writeFile(state) {
+        const writeResult = await this.sandboxWriteFile.call({
+            containerId: state.containerId,
+            path: '/workspace/result.txt',
+            content: 'Hello from sandbox!',
+            encoding: 'utf8',
+            createParentDirs: true,
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `File written: ${writeResult.data.path} (${writeResult.data.bytesWritten} bytes)`,
+        });
+    }
+    async readFile(state) {
+        const readResult = await this.sandboxReadFile.call({
+            containerId: state.containerId,
+            path: '/workspace/result.txt',
+            encoding: 'utf8',
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `File read successfully. Content: "${readResult.data.content}" (encoding: ${readResult.data.encoding})`,
+        });
+        this.assignState({ fileContent: readResult.data.content });
+    }
+    async listDir(state) {
+        const listResult = await this.sandboxListDirectory.call({
+            containerId: state.containerId,
+            path: '/workspace',
+            recursive: false,
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Directory listing for ${listResult.data.path}: ${this.formatEntries(listResult.data.entries)}`,
+        });
+        this.assignState({ fileList: listResult.data.entries });
+    }
+    async checkExists(state) {
+        const existsResult = await this.sandboxExists.call({
+            containerId: state.containerId,
+            path: '/workspace/result.txt',
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `File existence check: ${existsResult.data.path} exists=${existsResult.data.exists}, type=${existsResult.data.type}`,
+        });
+    }
+    async getInfo(state) {
+        const infoResult = await this.sandboxFileInfo.call({
+            containerId: state.containerId,
+            path: '/workspace/result.txt',
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `File info for ${infoResult.data.name}: type=${infoResult.data.type}, size=${infoResult.data.size} bytes, permissions=${infoResult.data.permissions}, owner=${infoResult.data.owner}`,
+        });
+    }
+    async deleteFile(state) {
+        const deleteResult = await this.sandboxDelete.call({
+            containerId: state.containerId,
+            path: '/workspace/result.txt',
+            recursive: false,
+            force: true,
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `File deleted: ${deleteResult.data.path} (deleted: ${deleteResult.data.deleted})`,
+        });
+    }
+    async destroySandbox(state) {
+        const destroyResult = await this.sandboxDestroy.call({
+            containerId: state.containerId,
+            removeContainer: true,
+        });
+        await this.documentStore.save(common_1.MessageDocument, {
+            role: 'assistant',
+            text: `Sandbox destroyed. Container ${destroyResult.data.containerId} removed=${destroyResult.data.removed}`,
+        });
+    }
+    formatEntries(entries) {
+        if (!entries || entries.length === 0) {
+            return '(empty)';
+        }
+        return entries.map((e) => `${e.name} (${e.type}, ${e.size} bytes)`).join(', ');
+    }
+};
+exports.SandboxExampleWorkflow = SandboxExampleWorkflow;
+__decorate([
+    (0, common_1.Transition)({ to: 'sandbox_ready' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "initSandbox", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'sandbox_ready', to: 'dir_created' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "createDir", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'dir_created', to: 'file_written' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "writeFile", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'file_written', to: 'file_read' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "readFile", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'file_read', to: 'dir_listed' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "listDir", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'dir_listed', to: 'existence_checked' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "checkExists", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'existence_checked', to: 'info_retrieved' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "getInfo", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'info_retrieved', to: 'file_deleted' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "deleteFile", null);
+__decorate([
+    (0, common_1.Transition)({ from: 'file_deleted', to: 'end' }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SandboxExampleWorkflow.prototype, "destroySandbox", null);
+exports.SandboxExampleWorkflow = SandboxExampleWorkflow = __decorate([
+    (0, common_1.Workflow)({
+        title: 'Filesystem - Sandbox Example',
+        description: 'Demonstrates the full Docker sandbox lifecycle: init a container, perform file operations (write, read, list, delete), and destroy the sandbox. Useful for isolated execution of untrusted code.',
+        schema: SandboxExampleArgsSchema,
+    }),
+    __metadata("design:paramtypes", [sandbox_tool_1.SandboxInit,
+        sandbox_tool_1.SandboxDestroy,
+        sandbox_filesystem_1.SandboxWriteFile,
+        sandbox_filesystem_1.SandboxReadFile,
+        sandbox_filesystem_1.SandboxListDirectory,
+        sandbox_filesystem_1.SandboxCreateDirectory,
+        sandbox_filesystem_1.SandboxDelete,
+        sandbox_filesystem_1.SandboxExists,
+        sandbox_filesystem_1.SandboxFileInfo])
+], SandboxExampleWorkflow);
+//# sourceMappingURL=sandbox-example.workflow.js.map

package/dist/workflows/sandbox/sandbox-example.workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-example.workflow.js","sourceRoot":"","sources":["../../../src/workflows/sandbox/sandbox-example.workflow.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@loopstack/filesystem-examples",
+  "displayName": "Loopstack Filesystem Examples",
+  "description": "Workflow examples for filesystem operations in Loopstack — Docker sandbox, remote file browsing, remote command execution, and local file tree.",
+  "keywords": [
+    "loopstack",
+    "example",
+    "filesystem",
+    "sandbox",
+    "remote",
+    "workflow"
+  ],
+  "version": "0.1.1",
+  "license": "MIT",
+  "author": {
+    "name": "Jakob Klippel",
+    "url": "https://www.linkedin.com/in/jakob-klippel/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./src/*": "./src/*"
+  },
+  "scripts": {
+    "build": "nest build",
+    "compile": "tsc --noEmit",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests",
+    "watch": "nest build --watch"
+  },
+  "dependencies": {
+    "@loopstack/common": "*",
+    "@loopstack/local-file-explorer-module": "*",
+    "@loopstack/remote-client": "*",
+    "@loopstack/remote-file-explorer-module": "*",
+    "@loopstack/sandbox-filesystem": "*",
+    "@loopstack/sandbox-tool": "*",
+    "@nestjs/common": "^11.1.19",
+    "zod": "^4.3.6"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "vitest": "^4.1.6",
+    "@swc/core": "^1.15.33",
+    "unplugin-swc": "^1.5.9"
+  }
+}

package/src/filesystem-examples.module.ts

@@ -0,0 +1,35 @@
+import { Module } from '@nestjs/common';
+import { StudioApp } from '@loopstack/common';
+import { LocalFileExplorerModule } from '@loopstack/local-file-explorer-module';
+import { RemoteClientModule } from '@loopstack/remote-client';
+import { RemoteFileExplorerModule } from '@loopstack/remote-file-explorer-module';
+import { SandboxFilesystemModule } from '@loopstack/sandbox-filesystem';
+import { SandboxToolModule } from '@loopstack/sandbox-tool';
+import { LocalFileExplorerExampleWorkflow } from './workflows/local-file-explorer/local-file-explorer-example.workflow';
+import { RemoteClientExampleWorkflow } from './workflows/remote-client/remote-client-example.workflow';
+import { RemoteFileExplorerExampleWorkflow } from './workflows/remote-file-explorer/remote-file-explorer-example.workflow';
+import { SandboxExampleWorkflow } from './workflows/sandbox/sandbox-example.workflow';
+
+const WORKFLOWS = [
+  SandboxExampleWorkflow,
+  RemoteFileExplorerExampleWorkflow,
+  RemoteClientExampleWorkflow,
+  LocalFileExplorerExampleWorkflow,
+];
+
+@StudioApp({
+  title: 'Filesystem Examples',
+  workflows: WORKFLOWS,
+})
+@Module({
+  imports: [
+    SandboxFilesystemModule,
+    SandboxToolModule,
+    RemoteFileExplorerModule.forFeature(),
+    RemoteClientModule.forFeature({ slots: [{ id: 'sandbox', type: 'sandbox', title: 'Sandbox' }] }),
+    LocalFileExplorerModule.forFeature(),
+  ],
+  providers: WORKFLOWS,
+  exports: WORKFLOWS,
+})
+export class FilesystemExamplesModule {}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './filesystem-examples.module';
+export * from './workflows/sandbox/sandbox-example.workflow';
+export * from './workflows/remote-file-explorer/remote-file-explorer-example.workflow';
+export * from './workflows/remote-client/remote-client-example.workflow';
+export * from './workflows/local-file-explorer/local-file-explorer-example.workflow';

package/src/workflows/local-file-explorer/local-file-explorer-example.workflow.ts

@@ -0,0 +1,34 @@
+import { BaseWorkflow, MarkdownDocument, Transition, Workflow } from '@loopstack/common';
+import { FileSystemService } from '@loopstack/local-file-explorer-module';
+
+interface LocalFileExplorerState {
+  fileCount?: number;
+}
+
+@Workflow({
+  title: 'Filesystem - Local File Explorer Example',
+  description:
+    'Demonstrates @loopstack/local-file-explorer-module — uses FileSystemService to build a file tree of the workspace root and render it as markdown. The module also exposes a REST API for the Studio file panel.',
+})
+export class LocalFileExplorerExampleWorkflow extends BaseWorkflow {
+  constructor(private readonly fileSystem: FileSystemService) {
+    super();
+  }
+
+  @Transition({ to: 'end' })
+  async listTree(_state: LocalFileExplorerState) {
+    const tree = await this.fileSystem.buildFileTree(process.cwd());
+    const lines = tree.slice(0, 50).map((node) => `- ${node.path} (${node.type})`);
+
+    await this.documentStore.save(MarkdownDocument, {
+      markdown: [
+        `# Workspace File Tree`,
+        '',
+        `Found ${tree.length} top-level entries in \`${process.cwd()}\`.`,
+        '',
+        ...lines,
+        tree.length > 50 ? `\n_(${tree.length - 50} more entries omitted)_` : '',
+      ].join('\n'),
+    });
+  }
+}

package/src/workflows/remote-client/remote-client-example.workflow.ts

@@ -0,0 +1,57 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import { BashTool, ReadTool, WriteTool } from '@loopstack/remote-client';
+
+interface RemoteClientState {
+  filePath?: string;
+}
+
+@Workflow({
+  title: 'Filesystem - Remote Client Example',
+  description:
+    'Demonstrates @loopstack/remote-client tools beyond file browsing: write a file, run a shell command on the remote machine via BashTool, read the result. Useful when you need command execution against a remote workspace.',
+})
+export class RemoteClientExampleWorkflow extends BaseWorkflow {
+  constructor(
+    private readonly bash: BashTool,
+    private readonly read: ReadTool,
+    private readonly write: WriteTool,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'file_written' })
+  async writeFile(_state: RemoteClientState) {
+    const filePath = '/tmp/remote-client-example.txt';
+    await this.write.call({
+      file_path: filePath,
+      content: 'Hello from RemoteClientExampleWorkflow!\n',
+    });
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Wrote file ${filePath}.`,
+    });
+    this.assignState({ filePath });
+  }
+
+  @Transition({ from: 'file_written', to: 'command_executed' })
+  async runCommand(state: RemoteClientState) {
+    const result = await this.bash.call({
+      command: `wc -l ${state.filePath} && date`,
+    });
+    const stdout = (result.data as { stdout?: string })?.stdout ?? '';
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Command output:\n\`\`\`\n${stdout}\n\`\`\``,
+    });
+  }
+
+  @Transition({ from: 'command_executed', to: 'end' })
+  async readBack(state: RemoteClientState) {
+    const result = await this.read.call({ file_path: state.filePath! });
+    const content = (result.data as { content?: string })?.content ?? '';
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Final file content:\n\`\`\`\n${content}\n\`\`\``,
+    });
+  }
+}

package/src/workflows/remote-file-explorer/remote-file-explorer-example.workflow.ts

@@ -0,0 +1,54 @@
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import { GlobTool, ReadTool } from '@loopstack/remote-client';
+
+interface RemoteFileExplorerState {
+  firstMatch?: string;
+}
+
+@Workflow({
+  title: 'Filesystem - Remote File Explorer Example',
+  description:
+    'Browses a remote workspace via @loopstack/remote-client GlobTool + ReadTool — finds Markdown files, reads the first match.',
+})
+export class RemoteFileExplorerExampleWorkflow extends BaseWorkflow {
+  constructor(
+    private readonly glob: GlobTool,
+    private readonly read: ReadTool,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'listed' })
+  async listFiles(_state: RemoteFileExplorerState) {
+    const result = await this.glob.call({ pattern: '**/*.md' });
+    const files = (result.data as { files?: string[] })?.files ?? [];
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Found ${files.length} markdown files:\n${files
+        .slice(0, 20)
+        .map((f) => `- ${f}`)
+        .join('\n')}`,
+    });
+    this.assignState({ firstMatch: files[0] });
+  }
+
+  @Transition({ from: 'listed', to: 'end' })
+  async readFirst(state: RemoteFileExplorerState) {
+    if (!state.firstMatch) {
+      await this.documentStore.save(MessageDocument, {
+        role: 'assistant',
+        text: 'No markdown files to read.',
+      });
+      return;
+    }
+
+    const result = await this.read.call({ file_path: state.firstMatch });
+    const content = (result.data as { content?: string })?.content ?? '';
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `# ${state.firstMatch}\n\n${content.slice(0, 500)}`,
+    });
+  }
+}

package/src/workflows/sandbox/sandbox-example.workflow.ts

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+import { BaseWorkflow, MessageDocument, Transition, Workflow } from '@loopstack/common';
+import type { RunContext } from '@loopstack/common';
+import {
+  SandboxCreateDirectory,
+  SandboxDelete,
+  SandboxExists,
+  SandboxFileInfo,
+  SandboxListDirectory,
+  SandboxReadFile,
+  SandboxWriteFile,
+} from '@loopstack/sandbox-filesystem';
+import { SandboxDestroy, SandboxInit } from '@loopstack/sandbox-tool';
+
+interface FileEntry {
+  name: string;
+  type: string;
+  size: number;
+  path: string;
+}
+
+interface SandboxExampleState {
+  containerId?: string;
+  fileContent?: string;
+  fileList?: FileEntry[];
+}
+
+const SandboxExampleArgsSchema = z.object({
+  outputDir: z.string().default(process.cwd() + '/out'),
+});
+
+type SandboxExampleArgs = z.infer<typeof SandboxExampleArgsSchema>;
+
+@Workflow({
+  title: 'Filesystem - Sandbox Example',
+  description:
+    'Demonstrates the full Docker sandbox lifecycle: init a container, perform file operations (write, read, list, delete), and destroy the sandbox. Useful for isolated execution of untrusted code.',
+  schema: SandboxExampleArgsSchema,
+})
+export class SandboxExampleWorkflow extends BaseWorkflow<SandboxExampleArgs> {
+  constructor(
+    // Sandbox lifecycle tools (from @loopstack/sandbox-tool)
+    private readonly sandboxInit: SandboxInit,
+    private readonly sandboxDestroy: SandboxDestroy,
+    // Filesystem tools (from @loopstack/sandbox-filesystem)
+    private readonly sandboxWriteFile: SandboxWriteFile,
+    private readonly sandboxReadFile: SandboxReadFile,
+    private readonly sandboxListDirectory: SandboxListDirectory,
+    private readonly sandboxCreateDirectory: SandboxCreateDirectory,
+    private readonly sandboxDelete: SandboxDelete,
+    private readonly sandboxExists: SandboxExists,
+    private readonly sandboxFileInfo: SandboxFileInfo,
+  ) {
+    super();
+  }
+
+  @Transition({ to: 'sandbox_ready' })
+  async initSandbox(state: SandboxExampleState, ctx: RunContext<SandboxExampleArgs>) {
+    const initResult = await this.sandboxInit.call({
+      containerId: 'my-sandbox',
+      imageName: 'node:18',
+      containerName: 'my-filesystem-sandbox',
+      projectOutPath: ctx.args.outputDir,
+      rootPath: 'workspace',
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Sandbox initialized successfully. Container ID: ${initResult.data.containerId}, Docker ID: ${initResult.data.dockerId}`,
+    });
+    this.assignState({ containerId: initResult.data.containerId });
+  }
+
+  @Transition({ from: 'sandbox_ready', to: 'dir_created' })
+  async createDir(state: SandboxExampleState) {
+    const mkdirResult = await this.sandboxCreateDirectory.call({
+      containerId: state.containerId!,
+      path: '/workspace',
+      recursive: true,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Directory created: ${mkdirResult.data.path} (created: ${mkdirResult.data.created})`,
+    });
+  }
+
+  @Transition({ from: 'dir_created', to: 'file_written' })
+  async writeFile(state: SandboxExampleState) {
+    const writeResult = await this.sandboxWriteFile.call({
+      containerId: state.containerId!,
+      path: '/workspace/result.txt',
+      content: 'Hello from sandbox!',
+      encoding: 'utf8',
+      createParentDirs: true,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `File written: ${writeResult.data.path} (${writeResult.data.bytesWritten} bytes)`,
+    });
+  }
+
+  @Transition({ from: 'file_written', to: 'file_read' })
+  async readFile(state: SandboxExampleState) {
+    const readResult = await this.sandboxReadFile.call({
+      containerId: state.containerId!,
+      path: '/workspace/result.txt',
+      encoding: 'utf8',
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `File read successfully. Content: "${readResult.data.content}" (encoding: ${readResult.data.encoding})`,
+    });
+    this.assignState({ fileContent: readResult.data.content });
+  }
+
+  @Transition({ from: 'file_read', to: 'dir_listed' })
+  async listDir(state: SandboxExampleState) {
+    const listResult = await this.sandboxListDirectory.call({
+      containerId: state.containerId!,
+      path: '/workspace',
+      recursive: false,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Directory listing for ${listResult.data.path}: ${this.formatEntries(listResult.data.entries)}`,
+    });
+    this.assignState({ fileList: listResult.data.entries });
+  }
+
+  @Transition({ from: 'dir_listed', to: 'existence_checked' })
+  async checkExists(state: SandboxExampleState) {
+    const existsResult = await this.sandboxExists.call({
+      containerId: state.containerId!,
+      path: '/workspace/result.txt',
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `File existence check: ${existsResult.data.path} exists=${existsResult.data.exists}, type=${existsResult.data.type}`,
+    });
+  }
+
+  @Transition({ from: 'existence_checked', to: 'info_retrieved' })
+  async getInfo(state: SandboxExampleState) {
+    const infoResult = await this.sandboxFileInfo.call({
+      containerId: state.containerId!,
+      path: '/workspace/result.txt',
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `File info for ${infoResult.data.name}: type=${infoResult.data.type}, size=${infoResult.data.size} bytes, permissions=${infoResult.data.permissions}, owner=${infoResult.data.owner}`,
+    });
+  }
+
+  @Transition({ from: 'info_retrieved', to: 'file_deleted' })
+  async deleteFile(state: SandboxExampleState) {
+    const deleteResult = await this.sandboxDelete.call({
+      containerId: state.containerId!,
+      path: '/workspace/result.txt',
+      recursive: false,
+      force: true,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `File deleted: ${deleteResult.data.path} (deleted: ${deleteResult.data.deleted})`,
+    });
+  }
+
+  @Transition({ from: 'file_deleted', to: 'end' })
+  async destroySandbox(state: SandboxExampleState) {
+    const destroyResult = await this.sandboxDestroy.call({
+      containerId: state.containerId!,
+      removeContainer: true,
+    });
+
+    await this.documentStore.save(MessageDocument, {
+      role: 'assistant',
+      text: `Sandbox destroyed. Container ${destroyResult.data.containerId} removed=${destroyResult.data.removed}`,
+    });
+  }
+
+  private formatEntries(entries: FileEntry[]): string {
+    if (!entries || entries.length === 0) {
+      return '(empty)';
+    }
+    return entries.map((e) => `${e.name} (${e.type}, ${e.size} bytes)`).join(', ');
+  }
+}