fix: opencode run uses positional argument, not --instruction flag

- opencode run takes prompt as positional [message..], not --instruction
- Updated legacy cli_map in daemon.py
- Updated all docs (configuration, engine-examples, troubleshooting, security)
- Fixed smoke.py test assertion
- Removed all --instruction references across the codebase

Author: nicolasramos

daemon.py

@@ -20,6 +20,7 @@
 import sys
 import time
 from datetime import datetime
+from urllib.parse import urlencode, urlparse
 
 import requests
 from dotenv import load_dotenv
@@ -51,13 +52,16 @@ def _first_present(*values):
 class OdooAgentRuntime:
     """Runtime daemon that connects to Odoo and executes agent work."""
 
-    def __init__(self, odoo_url, api_key, name, poll_interval=10, max_concurrent=3):
+    def __init__(self, odoo_url, api_key, name, poll_interval=10, max_concurrent=3, database=None):
         self.odoo_url = odoo_url.rstrip('/')
         self.api_key = api_key
         self.name = name
         self.poll_interval = poll_interval
         self.max_concurrent = max_concurrent
+        self.database = (database or '').strip() or None
         self.active_tasks = {}
+        self._database_bootstrapped = not self.database
+        self._database_bootstrap_failed = False
         self.session = requests.Session()
         self.session.headers.update({
             'X-API-Key': api_key,
@@ -67,8 +71,48 @@ def __init__(self, odoo_url, api_key, name, poll_interval=10, max_concurrent=3):
     def _api_url(self, path):
         return f'{self.odoo_url}{path}'
 
+    def _bootstrap_database_session(self):
+        """Select the configured Odoo database and retain its session cookie."""
+        if self._database_bootstrapped:
+            return True
+        if self._database_bootstrap_failed:
+            return False
+
+        login_url = f'{self.odoo_url}/web/login?{urlencode({"db": self.database})}'
+        try:
+            response = self.session.get(login_url, allow_redirects=True, timeout=30)
+            response.raise_for_status()
+        except requests.exceptions.RequestException as exc:
+            self._database_bootstrap_failed = True
+            logger.error(
+                'Database bootstrap failed for ODOO_DATABASE=%r: %s. '
+                'Runtime API calls were not attempted.',
+                self.database,
+                exc,
+            )
+            return False
+
+        final_url = getattr(response, 'url', '')
+        if (
+            isinstance(final_url, str)
+            and urlparse(final_url).path.rstrip('/') == '/web/database/selector'
+        ):
+            self._database_bootstrap_failed = True
+            logger.error(
+                'Database bootstrap failed for ODOO_DATABASE=%r: redirected to '
+                '/web/database/selector. Runtime API calls were not attempted.',
+                self.database,
+            )
+            return False
+
+        self._database_bootstrapped = True
+        logger.info('Selected Odoo database %r for this runtime session.', self.database)
+        return True
+
     def _request(self, method, path, **kwargs):
         """Make an API request with error handling."""
+        if not self._bootstrap_database_session():
+            return None
         try:
             resp = self.session.request(method, self._api_url(path), timeout=30, **kwargs)
             resp.raise_for_status()
@@ -310,7 +354,7 @@ def _resolve_command(self, agent_config, instruction, task_name, task_id):
 
         cli_map = {
             'hermes': ['hermes', 'run', '--task', task_name, '--context', instruction],
-            'opencode': ['opencode', 'run', '--instruction', instruction],
+            'opencode': ['opencode', 'run', instruction],
             'openclaw': ['openclaw', 'agent', '--task', task_name, '--context', instruction],
         }
 
@@ -390,6 +434,13 @@ def run(self):
         logger.info(f'Starting Odoo Agent Runtime: {self.name}')
         logger.info(f'Connecting to: {self.odoo_url}')
 
+        if not self._bootstrap_database_session():
+            logger.error(
+                'Cannot start runtime because ODOO_DATABASE bootstrap failed. '
+                'Verify the database name and Odoo access; this is not an API key error.'
+            )
+            return False
+
         if not self.send_heartbeat():
             logger.error('Failed to connect to Odoo. Check URL and API key.')
             return False
@@ -443,6 +494,8 @@ def main():
     parser = argparse.ArgumentParser(description='Odoo Agent Runtime Daemon')
     parser.add_argument('--odoo-url', default=os.getenv('ODOO_URL', 'http://localhost:8069'),
                         help='Odoo instance URL')
+    parser.add_argument('--odoo-database', default=os.getenv('ODOO_DATABASE', ''),
+                        help='Optional Odoo database for multi-database instances')
     parser.add_argument('--api-key', default=os.getenv('API_KEY', ''),
                         help='Runtime API key')
     parser.add_argument('--name', default=os.getenv('RUNTIME_NAME', get_hostname()),
@@ -464,6 +517,7 @@ def main():
         api_key=args.api_key,
         name=args.name,
         poll_interval=args.poll_interval,
+        database=args.odoo_database,
     )
 
     success = runtime.run()

docs/configuration.md

@@ -7,6 +7,8 @@ The runtime can be configured through `.env` or command-line flags.
 ```env
 ODOO_URL=https://odoo.example.com
 API_KEY=your-runtime-api-key
+# Optional: select this Odoo database before runtime API calls.
+ODOO_DATABASE=production
 RUNTIME_NAME=agent-worker-01
 POLL_INTERVAL=10
 ```
@@ -17,10 +19,24 @@ POLL_INTERVAL=10
 python3 daemon.py \
   --odoo-url https://odoo.example.com \
   --api-key your-runtime-api-key \
+  --odoo-database production \
   --name agent-worker-01 \
   --poll-interval 10
 ```
 
+## Multi-database Odoo
+
+`ODOO_DATABASE` (or `--odoo-database`) is optional. Configure it only when the
+Odoo server hosts more than one database and the runtime must use a specific
+one. Leaving it unset or blank preserves the existing single-database behavior.
+
+Before making runtime API calls, the runtime selects the configured database by
+requesting `/web/login?db=<URL-encoded database>` and following redirects. The
+resulting session cookie is retained and used for subsequent runtime API calls.
+
+Keep the Odoo URL free of credentials and API keys. Set `API_KEY` through the
+environment variable or `--api-key` flag; never put API keys in a URL.
+
 ## Poll interval
 
 Start with `10` seconds. Lower values feel more responsive but increase traffic. Higher values reduce traffic but make queues feel slower.
@@ -58,5 +74,5 @@ Supported placeholders:
 Example:
 
 ```text
-opencode run --instruction {instruction}
+opencode run {instruction}
 ```

docs/engine-examples.md

@@ -14,7 +14,7 @@ The runtime uses `agent.cli_command` from Odoo when present. Keep commands expli
 ## Examples
 
 ```text
-opencode run --instruction {instruction}
+opencode run {instruction}
 hermes run --context {instruction}
 openclaw agent --task {task_name} --context {instruction}
 claude --print {instruction}

docs/security.md

@@ -30,7 +30,7 @@ The runtime executes agent `cli_command` values configured in Odoo. Review those
 Prefer direct executable invocation:
 
 ```text
-opencode run --instruction {instruction}
+opencode run {instruction}
 ```
 
 Avoid commands that download and execute remote scripts.

docs/troubleshooting.md

@@ -51,7 +51,7 @@ Get-Command opencode
 Prefer placeholder-based commands:
 
 ```text
-opencode run --instruction {instruction}
+opencode run {instruction}
 ```
 
 Avoid shell-specific command strings when possible.

scripts/smoke.py

@@ -65,7 +65,7 @@ def main():
         {
             'name': 'Example',
             'engine': 'custom',
-            'cli_command': 'agent-cli run --instruction {instruction} --name "{task_name}"',
+            'cli_command': 'agent-cli run {instruction} --name "{task_name}"',
         },
         complex_instruction,
         'Task with spaces',
@@ -74,7 +74,6 @@ def main():
     assert cmd == [
         'agent-cli',
         'run',
-        '--instruction',
         complex_instruction,
         '--name',
         'Task with spaces',