microdao-daarion/docs/runbooks/NODE1_FILE_TOOL_SYNC_RUNBOOK.md

NODE1 File Tool Sync Runbook

Scope

This runbook documents:

• how NODE1 runtime drift was identified and synchronized,
• how universal file_tool was introduced into the actual NODE1 router stack,
• how to deploy and rollback safely.

Canonical Runtime (NODE1)

• Host: 144.76.224.179
• Runtime repo: /opt/microdao-daarion
• Compose: /opt/microdao-daarion/docker-compose.node1.yml
• Router container: dagi-router-node1
• Gateway container: dagi-gateway-node1
• Router API contract: POST /v1/agents/{agent_id}/infer (not /route)

Drift Findings (before sync)

The laptop had multiple repos; only this repo matches NODE1 architecture:

• /Users/apple/github-projects/microdao-daarion

Critical files were drifted against NODE1 runtime (15 files):

• docker-compose.node1.yml
• gateway-bot/agent_registry.json
• gateway-bot/http_api.py
• gateway-bot/router_client.py
• gateway-bot/senpai_prompt.txt
• http_api.py
• services/router/agent_tools_config.py
• services/router/main.py
• services/router/memory_retrieval.py
• services/router/requirements.txt
• services/router/router-config.yml
• services/router/tool_manager.py
• services/senpai-md-consumer/senpai/md_consumer/main.py
• services/senpai-md-consumer/senpai/md_consumer/publisher.py
• services/swapper-service/requirements.txt

Sync Procedure (NODE1 -> Laptop)

1. Snapshot and compare hashes:
   • compute SHA256 for the critical file list on laptop and NODE1.
2. Backup local copies:
   • rollback_backups/node1_sync_<timestamp>/...
3. Copy runtime files from NODE1 to laptop:
   • scp root@144.76.224.179:/opt/microdao-daarion/<file> ...
4. Verify 1:1 hash match.

File Tool Implementation

Implemented in actual NODE1 stack (services/router/* + gateway):

Added actions

• excel_create
• excel_update
• csv_create
• csv_update
• json_export
• yaml_export
• zip_bundle
• docx_create
• docx_update
• pptx_create
• pptx_update
• ods_create
• ods_update
• parquet_create
• parquet_update
• pdf_merge
• pdf_split
• pdf_fill
• pdf_update
• text_create
• text_update
• markdown_create
• markdown_update
• xml_export
• html_export
• image_create
• image_edit
• image_convert
• image_bundle
• svg_export
• svg_to_png

Standard output contract

For file-producing tool calls, router now propagates:

• file_base64
• file_name
• file_mime
• message (inside tool result payload)

Gateway behavior

gateway-bot/http_api.py now sends Telegram sendDocument when file fields are present.

Changed Files

• services/router/requirements.txt
• services/router/agent_tools_config.py
• services/router/tool_manager.py
• services/router/main.py
• gateway-bot/router_client.py
• gateway-bot/http_api.py

Deployment Steps (NODE1)

1. Backup target files on NODE1 before each step.
2. Sync updated files to /opt/microdao-daarion.
3. Compile checks:
   • python3 -m py_compile services/router/tool_manager.py services/router/main.py services/router/agent_tools_config.py gateway-bot/router_client.py gateway-bot/http_api.py
4. Rebuild/restart runtime services:
   • docker compose -f docker-compose.node1.yml up -d --build --no-deps router gateway
5. Health checks:
   • curl http://127.0.0.1:9102/health
   • curl http://127.0.0.1:9300/health

Smoke Tests

Run inside dagi-router-node1 to validate actions deterministically:

• Excel create/update
• Text/Markdown create/update
• XML/HTML export
• PPTX create/update
• ODS create/update
• Parquet create/update
• CSV create/update
• JSON/YAML export
• ZIP bundle
• DOCX create/update
• PDF merge/split/fill
• PDF update (rotate/reorder/remove/extract/metadata)
• Image create/edit/convert
• Image bundle (zip)
• SVG export + SVG->PNG convert (rect/circle/ellipse/line/polyline/polygon/text)

Also verify infer endpoint still works:

• POST http://127.0.0.1:9102/v1/agents/devtools/infer

Backups Created During This Work

• rollback_backups/file_tool_step1_20260215_011637/...
• rollback_backups/file_tool_step2_tool_manager.py.bak_20260215_012029
• rollback_backups/file_tool_step3_tool_manager.py.bak_20260215_012200
• rollback_backups/file_tool_step4_tool_manager.py.bak_20260215_012309
• services/router/tool_manager.py.bak_20260215_020902
• services/router/tool_manager.py.bak_20260215_112313
• services/router/tool_manager.py.bak_20260215_112459
• services/router/requirements.txt.bak_20260215_112459
• services/router/tool_manager.py.bak_20260215_112652
• services/router/requirements.txt.bak_20260215_112652
• services/router/tool_manager.py.bak_20260215_112841
• services/router/tool_manager.py.bak_20260215_112912
• services/router/tool_manager.py.bak_20260215_113301
• services/router/tool_manager.py.bak_20260215_114512
• services/router/tool_manager.py.bak_20260215_114740

Rollback (NODE1)

cd /opt/microdao-daarion
cp rollback_backups/file_tool_step1_20260215_011637/services/router/requirements.txt services/router/requirements.txt
cp rollback_backups/file_tool_step1_20260215_011637/services/router/agent_tools_config.py services/router/agent_tools_config.py
cp rollback_backups/file_tool_step1_20260215_011637/services/router/tool_manager.py services/router/tool_manager.py
cp rollback_backups/file_tool_step1_20260215_011637/services/router/main.py services/router/main.py
cp rollback_backups/file_tool_step1_20260215_011637/gateway-bot/router_client.py gateway-bot/router_client.py
cp rollback_backups/file_tool_step1_20260215_011637/gateway-bot/http_api.py gateway-bot/http_api.py

docker compose -f docker-compose.node1.yml up -d --build --no-deps router gateway

Notes

• docker-compose.node1.yml may warn about deprecated version key; this is non-blocking.
• Avoid --remove-orphans unless explicitly intended.
• Use --no-deps for targeted router/gateway rollout to avoid unrelated service churn.