feat(tools): use_oci + describe_oci — open-spec OCI control plane for agents

[fede-kamel]

Closes #253.

Summary

Two built-in tools that, together, expose every operation in the OCI Python SDK to an agent through a single open-spec primitive — no per-service plumbing.

• describe_oci(service?, client?, operation?) — runtime introspection. Progressively zooms into the SDK:

  • no args → list every service module under oci.* (~190 of them)
  • service → list every *Client class in that module
  • service + client → list operations, partitioned read-only vs mutating
  • service + client + operation → parameter schema parsed from the OCI SDK :param: docstring + signature

• use_oci(service, client, operation, parameters, ...) — execute any operation. Builds the right oci.<service>.<Client> with the requested auth (api_key, security_token, instance_principal, resource_principal), invokes the method, and serialises the response (snake_case Python attrs → camelCase wire names via attribute_map). Result includes http_status + opc-request-id for OCI-side traceability.

The agent loop becomes:

from locus.agent import Agent
from locus.models import get_model
from locus.tools import describe_oci, use_oci

agent = Agent(
    model=get_model("oci:openai.gpt-4o", profile="MY_GENAI", region="us-chicago-1"),
    tools=[describe_oci, use_oci],
    system_prompt="You can call OCI. Discover with describe_oci first, then use_oci.",
)
agent.run_sync("Are there any compute instances running anywhere in my tenancy?")

The model autonomously:

1. Calls describe_oci(service=\"core\", client=\"ComputeClient\", operation=\"list_instances\") to learn the parameter shape.
2. Calls use_oci(...) three times — once per subscribed region.
3. Returns an English summary citing the real instance name + OCID it found.

Adding a new OCI resource type to an agent no longer requires writing or registering any new code — one execution path, one auth code-path, one serialiser, one mutation gate for all of OCI.

Safety

use_oci is read-only by default. Operation names not starting with list_/get_/head_/summarize_/describe_/search_/fetch_/compute_/preview_/validate_/test_ are refused unless either allow_mutations=True is passed explicitly or LOCUS_USE_OCI_ALLOW_MUTATIONS=1 is set. Enforced in code, not via interactive prompt (locus tools must be non-interactive).

What's in the PR

• src/locus/tools/oci.py — both tools, the docstring parser, the OCI-model serialiser, and the auth router
• src/locus/tools/builtins.py + src/locus/tools/__init__.py — re-exports
• examples/notebook_70_oci_tools.py — three-part walkthrough: introspection, direct dispatch, agent-driven NL

Test plan

• uv run pytest tests/unit/test_tools.py tests/unit/test_tools_schema.py tests/unit/test_idempotent_tools.py — 71/71 pass.
• Pre-commit (ruff lint + format, mypy, codespell, secret scan) — clean.
• Live smoke against a real tenancy, read-only:
  • identity.IdentityClient.list_compartments → http_status=200, returned the tenancy's compartments with real opc-request-id.
  • object_storage.ObjectStorageClient.get_namespace (cross-region against us-chicago-1) → http_status=200, returned the real namespace.
  • core.ComputeClient.list_instances across three subscribed regions → returned the running instance with its real OCID.
• Safety gate: delete_bucket without allow_mutations → refused with explanatory error.
• describe_oci() returns 189 service modules; the docstring parser correctly extracts compartment_id (required), compartment_id_in_subtree (optional bool), access_level (optional str), etc. from list_compartments.

Narrative writeup

For a friendlier explanation of why this primitive matters — the design tradeoffs, the discover-then-execute pattern, a live trace against a real tenancy — see this gist:

https://gist.github.com/fede-kamel/d697e19290e94ecb00791e6dc1ff7d30