toolcraft-openapi should expose usable inputs for nested request fields like api_key_reference

[kamilio]

Summary

toolcraft-openapi-generate currently preserves nested request objects as opaque S.Json() parameters. That means important nested fields that are present in the OpenAPI schema, such as plan.api_bot_settings.api_key_reference, do not get a usable generated CLI/MCP/SDK input surface.

This showed up in the poe-agent-tools canary repo while validating the internal agent OpenAPI spec.

Repro

In poe-agent-tools, generate directly from the branch OpenAPI URL:

npm run generate

with:

toolcraft-openapi-generate \
  --input https://kjopek.main.quora.com/api/internal_agent/openapi.json \
  --output src/generated \
  --lock openapi.lock

The generated spec contains api_key_reference:

{
  "components": {
    "schemas": {
      "ApiBotSettingsPlan-Input": {
        "properties": {
          "api_key_reference": {
            "$ref": "#/components/schemas/ApiKeyReferencePlan"
          }
        },
        "required": ["model_name", "base_url", "api_key_reference", "api_type"]
      }
    }
  }
}

But the generated command only exposes plan as generic JSON:

params: S.Object({
  plan: S.Json(),
  // ...
})

So users do not see or get help/validation for api_key_reference as a first-class input, even though it is required inside plan.api_bot_settings.

Observed behavior

create-api-bot exposes top-level request fields like --api-key, because CreateApiBotRequest.api_key is a top-level property. But api_key_reference remains hidden inside the --plan JSON blob because it is nested under:

CreateApiBotRequest.plan -> BotCreationPlan-Input.api_bot_settings -> ApiBotSettingsPlan-Input.api_key_reference

This makes it look like generation missed api_key_reference, when the spec is actually carrying it.

Expected behavior

toolcraft-openapi should provide a better generated surface for nested request fields, especially required nested object properties. Possible directions:

• generate typed object schemas instead of collapsing nested objects to S.Json();
• support structured JSON helper params for nested object fields;
• optionally flatten selected nested fields into CLI-safe option names;
• at minimum, make required nested fields visible in generated help/schema metadata so users can discover them.

Why this belongs upstream

The canary repo should not patch the fetched spec or generated files. The OpenAPI document already includes the field. The gap is in how toolcraft-openapi-generate maps nested request schemas into generated command inputs.

[poe-code-agent]

Issue was resolved by #e0a7531

Update poe-code via npm install -g poe-code@3.0.379