API Evangelist enhancements - Cognizant Neuro SAN Agent Service API

overlay: 1.0.0
info:
  title: API Evangelist enhancements - Cognizant Neuro SAN Agent Service API
  version: 1.0.0
extends: openapi/cognizant-technology-agentservice-api-openapi.yml
x-provenance:
  generated: '2026-11-04'
  method: generated
  source: Derived from the provider's own documentation (neuro-san README, docs/clients.md, docs/mcp_service.md, agent.proto comments) and from
    this repository's artifacts. Every action below adds context the published contract omits; none contradicts it and the original spec is never
    mutated.
  note: 'The single highest-value addition here is the servers[] block. The published contract has NO servers[] at all, which leaves a client
    with four paths and no host to send them to. The value added is TEMPLATED on purpose — neuro-san is self-hosted, so the host genuinely is
    a variable, and inventing a concrete Cognizant hostname would be a fabrication. 2026-11-04: refine split the verbatim contract into one working
    spec per gRPC service, so this overlay now extends the AgentService spec and the /api/v1/list action moved to the ConciergeService overlay
    beside it.'
actions:
- target: $
  description: Add a templated server. neuro-san is self-hosted software; the provider's own examples use http://localhost:8080 after the operator
    starts the server. The variables make the host and port explicit rather than guessed.
  update:
    servers:
    - url: '{scheme}://{host}:{port}'
      description: An operator-run neuro-san agent service. Not a Cognizant-hosted endpoint — Cognizant publishes the software, the operator runs
        the server.
      variables:
        scheme:
          default: http
          enum:
          - http
          - https
          description: The provider's documented examples use http on loopback. TLS termination is the operator's responsibility and is not required
            by the contract.
        host:
          default: localhost
          description: The host on which the operator runs server_main_loop.
        port:
          default: '8080'
          description: The port used throughout the provider's own curl examples in docs/mcp_service.md.
- target: $.info
  description: Correct the record on info.version and name the real upstream. The document's declared version is a generator default that has
    never tracked the software.
  update:
    x-upstream-version: 0.7.0
    x-upstream-version-released: '2026-09-03'
    x-version-warning: info.version is "0.0.1", a protoc-gen-openapi default. It does not track the neuro-san release. Read currency from the
      PyPI package version instead.
    x-license: Apache-2.0
    x-source-repository: https://github.com/cognizant-ai-lab/neuro-san
    x-generated-from: neuro_san/api/grpc/{concierge,agent,chat,mime_data}.proto via protoc-gen-openapi
    x-published-at-runtime: GET /api/v1/docs
- target: $
  description: Record the sibling surfaces this REST projection coexists with.
  update:
    x-surfaces:
      grpc:
        services:
        - dev.cognizant_ai.neuro_san.api.grpc.agent.AgentService
        - dev.cognizant_ai.neuro_san.api.grpc.concierge.ConciergeService
        note: The REST paths below are google.api.http annotations on these RPCs; gRPC is the source of truth, not a parallel implementation.
      mcp:
        protocol_version: '2025-06-18'
        transport: JSON-RPC 2.0 over HTTP POST
        path: /mcp
        note: Enabled with --mcp_enable=true. Each public agent network becomes one MCP tool. See mcp/cognizant-technology-tool-crosswalk.yml.
- target: $.paths['/api/v1/{agent_name}/streaming_chat'].post
  description: Document the streaming and continuation semantics. These are stated in agent.proto's comments and are load-bearing for any client,
    but the generated OpenAPI drops comments entirely, so a client reading only the spec would get them wrong.
  update:
    x-streaming:
      type: server-streaming
      framing: Any single response is always on one line; responses are never broken across multiple lines in the HTTP response, so a client can
        parse the stream line by line.
      answer_location: The answer to a query is in the LAST streamed AGENT_FRAMEWORK message — not the first message and not necessarily the final
        message of the stream.
      mcp_divergence: The MCP projection of this operation does not stream; it returns a single JSON-RPC payload.
    x-continuation:
      mechanism: chat_context
      how: The last AGENT_FRAMEWORK message before the stream closes carries a populated chat_context. Copy it whole-cloth into the chat_context
        of the next request to continue the conversation.
    x-idempotency:
      supported: false
      warning: No replay protection. Calling this twice starts two conversations and bills the operator's LLM provider twice. A retry after a
        timeout cannot be made safe from the client side.
    x-private-channel:
      field: sly_data
      note: An optional map deliberately excluded from the LLM chat stream. Keys may be referenced in the stream; values are passed programmatically
        to tools. Documented carrier for client-supplied API keys, usernames and session ids.
- target: $.paths['/api/v1/{agent_name}/connectivity'].get
  description: Record that connectivity output is deliberately partial.
  update:
    x-disclosure:
      note: Per connectivity.proto's own comment, server-side agent descriptions may withhold connectivity they deem private or too much of an
        implementation detail. Connectivity reported is only as much as the server wants a client to know — an empty or shallow result is not
        necessarily an error.
- target: $.components.schemas.Status
  description: Name the error model explicitly so a client does not expect RFC 9457.
  update:
    x-error-model: google.rpc.Status
    x-rfc9457: false
    x-note: Not application/problem+json. There is no type, title, status, detail or instance member. See errors/cognizant-technology-problem-types.yml.