Using oduit from a coding agent

oduit agent ... is the primary documented automation surface for external coding agents. Prefer it over the Python API for editor agents, bots, and other out-of-process automation.

This page is the single source of truth for:

• command sequence

• mutation policy

• payload expectations

• failure handling

Command Families

Default to the read-only inspection and planning commands:

• context

• inspect-addon, inspect-addons, and addon-doc

• plan-update

• preflight-addon-change

• prepare-addon-change

• locate-model and locate-field

• list-addon-tests, recommend-tests, and list-addon-models

• find-model-extensions and get-model-views

• doctor, list-addons, dependency-graph, explain-install-order, resolve-config, resolve-addon-root, get-addon-files, check-addons-installed, check-model-exists, check-field-exists, and list-duplicates

• direct parity wrappers when exact runtime / DB metadata is needed: inspect-ref, inspect-modules, inspect-subtypes, inspect-model, inspect-field, db-table, db-column, db-constraints, db-tables, db-m2m, performance-slow-queries, performance-table-scans, performance-indexes, manifest-check, and manifest-show

• query-model, read-record, search-count, and get-model-fields

Only mutate through the controlled mutation commands:

• install-module

• uninstall-module

• update-module

• create-addon

• export-lang

• test-summary

For split addon technical documentation, use:

• technical-evidence (beta_for_agents, controlled_source_mutation)

• technical-report (beta_for_agents, controlled_source_mutation)

• technical-doc-diff (beta_for_agents, safe_read_only)

• technical-doc-refresh (beta_for_agents, controlled_source_mutation)

• technical-doc-accept (beta_for_agents, controlled_source_mutation)

• technical-doc-check (beta_for_agents, safe_read_only)

• technical-doc-next (beta_for_agents, safe_read_only)

• technical-doc-status (beta_for_agents, safe_read_only)

Recommended Command Sequence

For a change like “add email3 to res.partner in my_partner”, use this loop:

1. Resolve the environment and confirm addon discovery.

   oduit --env dev agent context
   oduit --env dev agent inspect-addon my_partner
   oduit --env dev agent addon-doc my_partner
   

2. Inspect the model from the database and the addon source tree.

   oduit --env dev agent get-model-fields res.partner --attributes string,type,required
   oduit --env dev agent get-model-views res.partner --types form,tree --summary
   oduit --env dev agent locate-model res.partner --module my_partner
   oduit --env dev agent locate-field res.partner email3 --module my_partner
   oduit --env dev agent list-addon-tests my_partner --model res.partner --field email3
   

   Use list-addon-models or find-model-extensions when the owning addon or the cross-addon extension surface is still unclear.

3. Plan the mutation before changing anything.

   oduit --env dev agent plan-update my_partner
   

   Or bundle the common read-only planning context into one payload:

   oduit --env dev agent prepare-addon-change my_partner --model res.partner --field email3 --types form,tree
   

   After editing specific files, map them back to focused tests:

   oduit --env dev agent recommend-tests --module my_partner --paths models/res_partner.py,views/res_partner_views.xml
   

4. Apply the mutation explicitly.

   oduit --env dev agent update-module my_partner --allow-mutation
   

5. Verify the result with targeted tests.

   oduit --env dev agent test-summary --module my_partner --test-tags /my_partner
   

For runtime spot checks after a change, prefer query-model, read-record, and search-count over arbitrary code execution.

When an agent needs direct parity with the human inspection / DB / manifest commands, use the structured wrappers instead of shell snippets:

oduit --env dev agent inspect-ref base.action_partner_form
oduit --env dev agent inspect-cron base.ir_cron_autovacuum
oduit --env dev agent inspect-model res.partner
oduit --env dev agent inspect-field res.partner email --with-db
oduit --env dev agent db-table res_partner
oduit --env dev agent manifest-check sale
oduit --env dev agent explain-install-order --modules sale

For a cheap read-only planning and health pass before mutating an addon, use preflight-addon-change:

oduit --env dev agent preflight-addon-change my_partner --model res.partner --field email3

For a single end-to-end runtime verification pass after editing one addon, use validate-addon-change:

oduit --env dev agent validate-addon-change my_partner --allow-mutation --update --discover-tests

This command inspects the addon, checks environment health and duplicate names, optionally installs or updates the addon, runs the full module test suite using /<module> test tags by default, and returns one aggregate payload with sub-results for each step.

Mutation Policy

• Default to read-only commands.

• install-module, uninstall-module, update-module, create-addon, and export-lang are controlled mutations.

• inspect-cron is read-only by default; inspect-cron --trigger becomes a controlled runtime mutation and may require --allow-mutation.

• Runtime DB mutation uses explicit flags:

  • write_protect_db blocks runtime DB mutation for every caller

  • needs_mutation_flag requires --allow-mutation for human runtime DB mutation

  • agent_write_protect_db blocks runtime DB mutation for agent commands

  • agent_needs_mutation_flag requires --allow-mutation for agent runtime DB mutation

• Controlled source mutations still require --allow-mutation regardless of runtime DB policy flags.

• uninstall-module also requires --allow-uninstall and allow_uninstall = true in the active environment config.

• --dry-run is supported by install-module, uninstall-module, update-module, create-addon, and export-lang. Their dry runs return read-only planning payloads.

• test-summary stays read-only unless you pass --install or --update. validate-addon-change only consults runtime DB mutation policy when you request install or update work.

• If context, resolve-config, or list-duplicates reports blockers, fix them before mutating.

• Do not use execute_python_code() or OdooCodeExecutor for routine coding-agent automation. Reserve them for trusted operator-controlled paths.

Payload Expectations

Every final-result agent command emits exactly one JSON object on stdout. Raw command metadata is hidden by default; opt in with oduit agent --show-command ... when data.command is needed for debugging.

Guaranteed top-level keys:

• schema_version

• type

• success

• read_only

• safety_level

• warnings

• errors

• remediation

• data

• meta

When available, commands also include:

• operation

• error

• error_type

• error_code

data is the canonical command payload container:

• command-specific fields such as module, count, or candidates live under data

• meta.timestamp is the canonical payload creation time

• meta.duration remains optional when timing data is available

• top-level timestamp aliases are not part of the agent contract

When --show-command is enabled, the raw command is exposed as data.command.

Technical-documentation payload notes:

• preview payloads include would_write, would_write_metadata, and preview

• --include-markdown is opt-in for full markdown output in agent payloads

• write commands return relative output paths for changed files

• technical-doc-check, technical-doc-status, and technical-doc-next default to compact file listings unless --include-files is passed

• final payload JSON stays on stdout; progress output remains on stderr

For source-location commands, prefer explicit decision fields over raw confidence alone:

• data.resolution: overall result such as confirmed, ambiguous, suggested, or not_found

• data.ambiguous / data.ambiguity_reason: whether the command found multiple plausible matches

• data.candidates[*].match_strength and data.candidates[*].evidence: why a candidate was chosen and whether it is a confirmed source hit or a best-effort suggestion

Compatibility Policy

• additive fields are allowed within schema_version = 2.x

• consumers must read command-specific data from payload["data"]

• meta.timestamp is the canonical creation timestamp

• flattened command-field aliases and generated_at are not part of the supported agent contract

Payload Stability Tiers

• stable: schema_version, type, operation, success,

  read_only, safety_level, warnings, errors, remediation, error, error_type, error_code, data, meta

• soft-stable: optional debug metadata such as data.command and optional timing data such as meta.duration

• experimental: newly introduced command-specific fields inside data that are not yet called out in the public docs

Command Stability Tiers

Use Agent command inventory for the generated command-by-command tier matrix.

• stable_for_agents: recommended machine-facing surface for coding agents

• beta_for_agents: useful for agents but still evolving in behavior, heuristics, or workflow shape

• human_oriented: supported CLI surface documented primarily for humans

• compatibility_only: retained for migration or import compatibility only

Safety Levels

• safe_read_only: inspection and analysis only

• controlled_runtime_mutation: explicit commands that mutate database, process, or runtime state, gated by flags such as --allow-mutation

• controlled_source_mutation: explicit commands that write or rewrite addon source files, also gated by flags such as --allow-mutation

• unsafe_arbitrary_execution: trusted arbitrary code execution only

Published Schemas

Published JSON Schema artifacts live under schemas/:

• schemas/result-envelope.schema.json

• schemas/agent/environment-context.schema.json

• schemas/agent/addon-info.schema.json

• schemas/agent/addon-documentation.schema.json

• schemas/agent/addon-inspection.schema.json

• schemas/agent/update-plan.schema.json

• schemas/agent/query-result.schema.json

• schemas/agent/model-source-location.schema.json

• schemas/agent/field-source-location.schema.json

• schemas/agent/addon-test-inventory.schema.json

• schemas/agent/addon-model-inventory.schema.json

• schemas/agent/model-extension-inventory.schema.json

• schemas/agent/model-view-inventory.schema.json

• schemas/agent/addon-root-resolution.schema.json

• schemas/agent/addon-file-inventory.schema.json

• schemas/agent/addon-install-checks.schema.json

• schemas/agent/model-existence.schema.json

• schemas/agent/field-existence.schema.json

• schemas/agent/addon-change-preflight.schema.json

• schemas/agent/addon-change-validation.schema.json

• schemas/agent/addon-change-context.schema.json

• schemas/agent/recommended-test-plan.schema.json

• schemas/agent/xmlid-inspection.schema.json

• schemas/agent/cron-inspection.schema.json

• schemas/agent/module-inspection.schema.json

• schemas/agent/subtype-inventory.schema.json

• schemas/agent/model-inspection.schema.json

• schemas/agent/field-inspection.schema.json

• schemas/agent/table-description.schema.json

• schemas/agent/column-description.schema.json

• schemas/agent/constraint-inventory.schema.json

• schemas/agent/table-inventory.schema.json

• schemas/agent/m2m-inspection.schema.json

• schemas/agent/slow-query-metrics.schema.json

• schemas/agent/table-scan-metrics.schema.json

• schemas/agent/index-usage-metrics.schema.json

• schemas/agent/manifest-validation.schema.json

• schemas/agent/manifest.schema.json

Failure Handling

• Always read both the process exit status and the payload success flag.

• Failure payloads still use the same JSON envelope and are emitted before the command exits non-zero.

• Prefer error for the human-readable summary.

• Prefer error_type for the stable failure category.

• Prefer error_code for the stable machine-branching key.

• Prefer errors for structured details.

• Prefer remediation for next actions the caller can take.

• ConfirmationRequired means a controlled runtime or source mutation was attempted without --allow-mutation.

• ConfigError usually means the environment config, resolved binaries, or addons_path needs to be fixed before retrying.

• ModuleNotFoundError means the requested addon was not resolved in the active addons_path.

• ValidationError means an input format such as --domain-json or a repeated filter option could not be parsed safely.

Example failure codes:

• config.addons_path_missing

• module.not_found

• mutation.confirmation_required

• runtime.test_failure

• runtime.install_dependency_error

• runtime.uninstall_dependency_blocked

When success = false, do not guess about the next step. Inspect the structured payload, follow remediation, reconcile state if needed, and then rerun the next targeted command.

Example

{
   "schema_version": "2.0",
   "type": "model_source_location",
   "success": true,
   "operation": "locate_model",
   "read_only": true,
   "safety_level": "safe_read_only",
   "warnings": [],
   "errors": [],
   "remediation": [],
   "data": {
      "model": "res.partner",
      "module": "my_partner",
      "addon_root": "/workspace/addons/my_partner",
      "resolution": "confirmed",
      "ambiguous": false,
      "candidates": [
         {
            "path": "/workspace/addons/my_partner/models/res_partner.py",
            "class_name": "ResPartner",
            "match_kind": "inherit",
            "declared_model": "res.partner",
            "confidence": 0.98,
            "match_strength": "confirmed",
            "evidence": [
               {
                  "kind": "model_inherit",
                  "message": "Class inherits `res.partner` directly in addon source.",
                  "path": "/workspace/addons/my_partner/models/res_partner.py",
                  "line_hint": 6
               }
            ],
            "line_hint": 6
         }
      ]
   },
   "meta": {
      "timestamp": "2026-04-09T12:00:00"
    }
 }